@hadoku/prefs-client 1.1.4 → 1.1.6

package/README.md

@@ -121,12 +121,15 @@ watchparty character.
 
 ## Avatars (`@wolffm/prefs-client/avatar`)
 
-One resolved avatar per hadoku user, chosen by the user at `hadoku.me/account`.
+One resolved avatar per hadoku user, chosen by the user in the fleet settings popout
+(`ConnectedSettings`, @wolffm/task-ui-components): the picture's source and their character.
 
 ```ts
-type ResolvedAvatar =
-  | { source: 'sprite'; sprite?: string } // watchparty character id; absent = your default
-  | { source: 'discord' | 'steam' | 'upload'; url: string }; // square https image, >= 184px
+interface ResolvedAvatar {
+  source: 'sprite' | 'discord' | 'steam' | 'upload'; // what the picture is
+  url?: string; // present exactly when source !== 'sprite': square https image, >= 184px
+  sprite?: string; // the person's character, WHATEVER the source; absent = your default
+}
 ```
 
 Browser, the signed-in user's own avatar:
@@ -152,12 +155,13 @@ Rules for an app that renders avatars:
 - **`url` → `<img src>`**, nothing else: never fetch it server-side, never proxy it. Set
   `referrerpolicy="no-referrer"`. A URL can stop working (a changed Discord picture, an admin
   removal): on `error`, fall back to the sprite.
-- **`sprite`**: the app that owns the sprite art builds its URL (watchparty owns art revisions).
-  Without a `sprite`, render your own default.
+- **`sprite`** is the character even when the picture is a Discord avatar: a game uses it as the
+  piece and its colour. The app that owns the art builds its URL (watchparty owns art revisions;
+  its public `GET /watchparty/api/characters` lists them). Without one, use your own default.
 - **Steam attribution is required** wherever a `steam` avatar is shown (Steam Web API terms): a
   visible line such as "Steam avatars via the Steam Web API · not affiliated with Valve", linking
   to `https://store.steampowered.com/`. Do not use Steam's or Discord's logos, and do not imply
   either endorses the app.
 - Resolve on join and on reconnect; avatars change rarely. `resolveAvatars` batches past 100 ids.
-- Source choice, linking, uploads and removal all happen on `hadoku.me/account` — link there
-  rather than building your own.
+- Source choice, character choice, linking (`linkInPopup`: no page navigation), uploads and
+  removal all happen in the settings popout. Don't build your own.

package/dist/avatar.d.ts

@@ -14,34 +14,48 @@ type LinkProvider = (typeof LINK_PROVIDERS)[number];
 /**
  * The one avatar every app renders for a user.
  *
- * - `sprite`: `sprite` is the watchparty character id from the user's
- *   watchparty prefs, or absent when they never picked one (render your own
- *   default). There is no `url`: the app that owns the sprite art owns its
- *   URL and its revision.
- * - `discord` / `steam` / `upload`: `url` is an absolute https image URL,
- *   square, at least 184px. Render it as an `<img>`; never fetch it server-side
- *   on a user's behalf.
+ * - `source` is what the picture is. `'sprite'` means the character is the
+ *   picture; any other source carries `url`.
+ * - `url` (present exactly when `source` is not `'sprite'`) is an absolute
+ *   https image URL, square, at least 184px, on a host the hadoku.me CSP admits.
+ *   Render it as an `<img>`; never fetch it server-side.
+ * - `sprite` is the person's character (a watchparty character id) whenever
+ *   they have one, WHATEVER the source: games use it as the piece and the
+ *   name colour even when the picture is a Discord avatar. Absent = never
+ *   picked; use your own default. The app that owns the art (watchparty, its
+ *   public GET /watchparty/api/characters) owns its URL and revision.
  *
- * A source that stops being available (an unlink, an admin removal, a Discord
- * avatar that changed) resolves to `sprite` with no action from the app.
+ * A source that stops being available (an unlink, an admin removal, an account
+ * whose custom avatar was removed) resolves to `sprite` with no action from the app.
  */
-type ResolvedAvatar = {
-    source: 'sprite';
+interface ResolvedAvatar {
+    source: AvatarSource;
+    url?: string;
     sprite?: string;
-    url?: undefined;
+}
+/** PUT /api/v1/_avatar — either or both. */
+interface AvatarUpdate {
+    source?: AvatarSource;
+    /** A watchparty character id (SPRITE_ID_PATTERN). */
+    sprite?: string;
+}
+/** What the callback page posts to the window that opened it (same origin only). */
+declare const LINK_MESSAGE_TYPE = "hadoku-avatar-link";
+type LinkMessage = {
+    type: typeof LINK_MESSAGE_TYPE;
+    ok: true;
+    provider: LinkProvider;
 } | {
-    source: 'discord' | 'steam' | 'upload';
-    url: string;
-    sprite?: undefined;
+    type: typeof LINK_MESSAGE_TYPE;
+    ok: false;
+    error: string;
 };
 /** A linked account as its owner sees it. Never carries a token. */
 interface LinkedAccountView {
-    /** null when the account has no custom avatar, or the cached one went stale. */
+    /** null when the account has no custom avatar. */
     avatarUrl: string | null;
     linkedAt: number;
     refreshedAt: number;
-    /** Set when Discord stopped serving the cached avatar: link again to pick up the new one. */
-    stale: boolean;
 }
 interface UploadView {
     url: string;
@@ -94,6 +108,8 @@ declare const SPRITE_ID_PATTERN: RegExp;
  */
 declare const LINK_CALLBACK_PATH = "/account/link/callback";
 
+/** sessionStorage key the callback page reads to know it runs in the link popup. */
+declare const LINK_POPUP_MARK = "hadoku-avatar-link-popup";
 declare class AvatarError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
@@ -108,6 +124,8 @@ declare function createAvatarClient(opts?: AvatarClientOptions): {
     get: () => Promise<AvatarSettings>;
     /** Pick a source. 409 when it is not available (not linked, nothing uploaded). */
     choose: (source: AvatarSource) => Promise<AvatarSettings>;
+    /** Set the source, the character, or both in one write. */
+    update: (u: AvatarUpdate) => Promise<AvatarSettings>;
     /**
      * Begin linking. Navigate the browser to the returned URL; the provider
      * returns it to hadoku.me/account/link/callback, which completes the link.
@@ -115,6 +133,15 @@ declare function createAvatarClient(opts?: AvatarClientOptions): {
      * Discord or Steam before they ask.
      */
     startLink: (provider: LinkProvider) => Promise<LinkStart>;
+    /**
+     * Link in a popup, so the page never navigates. Call it straight from the
+     * click handler: the window is opened before the first await, which is
+     * what popup blockers allow. Resolves with fresh settings once the popup
+     * reports back or is closed (closing is not an error: the settings say
+     * whether the link landed). Rejects only when the popup could not open
+     * or the link could not start.
+     */
+    linkInPopup: (provider: LinkProvider) => Promise<AvatarSettings>;
     /** Finish a link from the callback page's query string (`location.search`). */
     completeLink: (query: string) => Promise<AvatarSettings>;
     /** Delete the linked id and its cached avatar URL. */
@@ -134,4 +161,4 @@ interface ResolveAvatarsOptions extends AvatarClientOptions {
  */
 declare function resolveAvatars(opts: ResolveAvatarsOptions, userIds: readonly string[]): Promise<Record<string, ResolvedAvatar>>;
 
-export { AVATAR_SOURCES, type AvatarClient, type AvatarClientOptions, AvatarError, type AvatarSettings, type AvatarSource, type AvatarUploadLimits, LINK_CALLBACK_PATH, LINK_PROVIDERS, type LinkProvider, type LinkStart, type LinkedAccountView, RESOLVE_MAX_IDS, type ResolveAvatarsOptions, type ResolveRequest, type ResolveResponse, type ResolvedAvatar, SPRITE_ID_PATTERN, type UploadView, createAvatarClient, resolveAvatars };
+export { AVATAR_SOURCES, type AvatarClient, type AvatarClientOptions, AvatarError, type AvatarSettings, type AvatarSource, type AvatarUpdate, type AvatarUploadLimits, LINK_CALLBACK_PATH, LINK_MESSAGE_TYPE, LINK_POPUP_MARK, LINK_PROVIDERS, type LinkMessage, type LinkProvider, type LinkStart, type LinkedAccountView, RESOLVE_MAX_IDS, type ResolveAvatarsOptions, type ResolveRequest, type ResolveResponse, type ResolvedAvatar, SPRITE_ID_PATTERN, type UploadView, createAvatarClient, resolveAvatars };

package/dist/avatar.js

@@ -4,11 +4,21 @@ var PREFS_API_BASE = "https://hadoku.me/prefs";
 // src/avatar-contract.ts
 var AVATAR_SOURCES = ["sprite", "discord", "steam", "upload"];
 var LINK_PROVIDERS = ["discord", "steam"];
+var LINK_MESSAGE_TYPE = "hadoku-avatar-link";
 var RESOLVE_MAX_IDS = 100;
 var SPRITE_ID_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
 var LINK_CALLBACK_PATH = "/account/link/callback";
 
 // src/avatar.ts
+var LINK_WINDOW_NAME = "hadoku-avatar-link";
+var LINK_POPUP_MARK = "hadoku-avatar-link-popup";
+function markPopup(on) {
+  try {
+    if (on) sessionStorage.setItem(LINK_POPUP_MARK, "1");
+    else sessionStorage.removeItem(LINK_POPUP_MARK);
+  } catch {
+  }
+}
 var AvatarError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -32,11 +42,52 @@ function createAvatarClient(opts = {}) {
     method,
     ...body === void 0 ? {} : { headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }
   });
+  const getSettings = () => call("");
+  async function linkInPopup(provider) {
+    markPopup(true);
+    const popup = window.open("about:blank", LINK_WINDOW_NAME, "popup,width=520,height=760");
+    markPopup(false);
+    if (!popup)
+      throw new AvatarError(0, "The sign-in window was blocked: allow pop-ups for hadoku.me");
+    let authorizeUrl;
+    try {
+      ({ authorizeUrl } = await send(`/link/${provider}`, "POST", {}));
+    } catch (err) {
+      popup.close();
+      throw err;
+    }
+    popup.location.href = authorizeUrl;
+    return new Promise((resolve, reject) => {
+      const channel = new BroadcastChannel(LINK_MESSAGE_TYPE);
+      let settled = false;
+      const finish = (failure) => {
+        if (settled) return;
+        settled = true;
+        channel.close();
+        clearInterval(closedPoll);
+        clearTimeout(giveUp);
+        if (failure) reject(new AvatarError(400, failure));
+        else getSettings().then(resolve, reject);
+      };
+      channel.onmessage = (e) => {
+        if (e.data?.type !== LINK_MESSAGE_TYPE) return;
+        finish(e.data.ok ? void 0 : e.data.error);
+      };
+      const closedPoll = setInterval(() => {
+        if (!popup.closed) return;
+        clearInterval(closedPoll);
+        setTimeout(() => finish(), 1500);
+      }, 500);
+      const giveUp = setTimeout(() => finish(), 10 * 60 * 1e3);
+    });
+  }
   return {
     /** The caller's settings, including the resolved avatar. */
-    get: () => call(""),
+    get: getSettings,
     /** Pick a source. 409 when it is not available (not linked, nothing uploaded). */
     choose: (source) => send("", "PUT", { source }),
+    /** Set the source, the character, or both in one write. */
+    update: (u) => send("", "PUT", u),
     /**
      * Begin linking. Navigate the browser to the returned URL; the provider
      * returns it to hadoku.me/account/link/callback, which completes the link.
@@ -44,6 +95,15 @@ function createAvatarClient(opts = {}) {
      * Discord or Steam before they ask.
      */
     startLink: (provider) => send(`/link/${provider}`, "POST", {}),
+    /**
+     * Link in a popup, so the page never navigates. Call it straight from the
+     * click handler: the window is opened before the first await, which is
+     * what popup blockers allow. Resolves with fresh settings once the popup
+     * reports back or is closed (closing is not an error: the settings say
+     * whether the link landed). Rejects only when the popup could not open
+     * or the link could not start.
+     */
+    linkInPopup: (provider) => linkInPopup(provider),
     /** Finish a link from the callback page's query string (`location.search`). */
     completeLink: (query) => send("/link/complete", "POST", { query: query.replace(/^\?/, "") }),
     /** Delete the linked id and its cached avatar URL. */
@@ -72,6 +132,8 @@ export {
   AVATAR_SOURCES,
   AvatarError,
   LINK_CALLBACK_PATH,
+  LINK_MESSAGE_TYPE,
+  LINK_POPUP_MARK,
   LINK_PROVIDERS,
   RESOLVE_MAX_IDS,
   SPRITE_ID_PATTERN,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadoku/prefs-client",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Client SDK for the hadoku unified preferences store. Wraps /prefs/api/v1/* with localStorage caching, debounced writes, Zod-validated reads, and a usePrefs() React hook, plus match history, ratings and leaderboards for every game (./games), and the one resolved avatar per user (./avatar).",
   "type": "module",
   "main": "./dist/index.js",