@hadoku/prefs-client 1.1.2 → 1.1.3

package/README.md

@@ -96,3 +96,46 @@ const client = createPrefsClient({
   // storage auto-detects Capacitor; pass an explicit adapter only to override
 });
 ```
+
+## Avatars (`@wolffm/prefs-client/avatar`)
+
+One resolved avatar per hadoku user, chosen by the user at `hadoku.me/account`.
+
+```ts
+type ResolvedAvatar =
+  | { source: 'sprite'; sprite?: string } // watchparty character id; absent = your default
+  | { source: 'discord' | 'steam' | 'upload'; url: string }; // square https image, >= 184px
+```
+
+Browser, the signed-in user's own avatar:
+
+```ts
+import { createAvatarClient } from '@wolffm/prefs-client/avatar';
+const { avatar } = await createAvatarClient().get(); // AvatarSettings
+```
+
+Server, everyone in a room, by userId, with the server's service-tier key:
+
+```ts
+import { resolveAvatars } from '@wolffm/prefs-client/avatar';
+const byUser = await resolveAvatars(
+  { serviceKey: process.env.SERVICE_KEY! },
+  userIds
+);
+// every requested id is present; unknown users resolve to { source: 'sprite' }
+```
+
+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.
+- **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.

package/dist/avatar.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Avatars — the wire contract, shared by prefs-api and the client.
+ *
+ * Pure: no fetch, no DOM. prefs-api imports this file directly (as it does
+ * games-contract.ts), so the server answers in the very types the client is
+ * built from. The client half lives in ./avatar.ts.
+ *
+ * Design: hadoku_site docs/planning/avatars-2026-10-30.md
+ */
+declare const AVATAR_SOURCES: readonly ["sprite", "discord", "steam", "upload"];
+type AvatarSource = (typeof AVATAR_SOURCES)[number];
+declare const LINK_PROVIDERS: readonly ["discord", "steam"];
+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.
+ *
+ * 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.
+ */
+type ResolvedAvatar = {
+    source: 'sprite';
+    sprite?: string;
+    url?: undefined;
+} | {
+    source: 'discord' | 'steam' | 'upload';
+    url: string;
+    sprite?: undefined;
+};
+/** 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. */
+    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;
+    width: number;
+    height: number;
+    uploadedAt: number;
+}
+/** GET /api/v1/_avatar — the caller's own avatar settings. */
+interface AvatarSettings {
+    avatar: ResolvedAvatar;
+    /** What the user picked; null = never picked (resolves to sprite). */
+    choice: AvatarSource | null;
+    sprite: string | null;
+    linked: Partial<Record<LinkProvider, LinkedAccountView>>;
+    upload: UploadView | null;
+    /** Whether each provider is configured on the server. A false one cannot be linked yet. */
+    providers: Record<LinkProvider, boolean>;
+    limits: AvatarUploadLimits;
+}
+interface AvatarUploadLimits {
+    maxBytes: number;
+    minDimension: number;
+    maxDimension: number;
+    acceptedTypes: readonly string[];
+    /** Accepted uploads per user per rolling 24h. */
+    perDay: number;
+    /** Edge length of the stored square, in px. */
+    outputSize: number;
+}
+/** POST /api/v1/_avatar/link/:provider → where to send the browser. */
+interface LinkStart {
+    authorizeUrl: string;
+}
+/** POST /api/v1/_avatar/resolve (service tier). At most RESOLVE_MAX_IDS ids. */
+interface ResolveRequest {
+    userIds: string[];
+}
+interface ResolveResponse {
+    /** Every requested id is present; an unknown user resolves to `{ source: 'sprite' }`. */
+    avatars: Record<string, ResolvedAvatar>;
+}
+declare const RESOLVE_MAX_IDS = 100;
+/** A watchparty character id, as prefs-api accepts one from the watchparty blob. */
+declare const SPRITE_ID_PATTERN: RegExp;
+/**
+ * Where Discord and Steam send the browser back. A hadoku.me page, not an API
+ * route: the session cookie is SameSite=Strict, so a navigation arriving from
+ * discord.com or steamcommunity.com carries no session. The page then POSTs
+ * the query string same-origin, where it does.
+ */
+declare const LINK_CALLBACK_PATH = "/account/link/callback";
+
+declare class AvatarError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+interface AvatarClientOptions {
+    /** The prefs mount (`https://hadoku.me/prefs` by default), without `/api/v1`. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+declare function createAvatarClient(opts?: AvatarClientOptions): {
+    /** The caller's settings, including the resolved avatar. */
+    get: () => Promise<AvatarSettings>;
+    /** Pick a source. 409 when it is not available (not linked, nothing uploaded). */
+    choose: (source: AvatarSource) => 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.
+     * Call this only from the user's own click: nothing is fetched from
+     * Discord or Steam before they ask.
+     */
+    startLink: (provider: LinkProvider) => Promise<LinkStart>;
+    /** 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. */
+    unlink: (provider: LinkProvider) => Promise<AvatarSettings>;
+    /** Upload an image (PNG, JPEG, WebP or GIF). It is re-encoded and becomes the chosen source. */
+    upload: (image: Blob) => Promise<AvatarSettings>;
+    removeUpload: () => Promise<AvatarSettings>;
+};
+type AvatarClient = ReturnType<typeof createAvatarClient>;
+interface ResolveAvatarsOptions extends AvatarClientOptions {
+    /** The game server's own service-tier key. */
+    serviceKey: string;
+}
+/**
+ * Server-side: resolve many users' avatars by userId. Batches past
+ * RESOLVE_MAX_IDS for you. Every requested id is in the result.
+ */
+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 };

package/dist/avatar.js

@@ -0,0 +1,80 @@
+// src/constants.ts
+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 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 AvatarError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AvatarError";
+  }
+  status;
+};
+async function readJson(res) {
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    throw new AvatarError(res.status, body?.message ?? `HTTP ${res.status}`);
+  }
+  return await res.json();
+}
+function createAvatarClient(opts = {}) {
+  const base = `${opts.baseUrl ?? PREFS_API_BASE}/api/v1/_avatar`;
+  const f = opts.fetch ?? fetch;
+  const call = (path, init = {}) => f(`${base}${path}`, { credentials: "include", ...init }).then(readJson);
+  const send = (path, method, body) => call(path, {
+    method,
+    ...body === void 0 ? {} : { headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }
+  });
+  return {
+    /** The caller's settings, including the resolved avatar. */
+    get: () => call(""),
+    /** Pick a source. 409 when it is not available (not linked, nothing uploaded). */
+    choose: (source) => send("", "PUT", { source }),
+    /**
+     * Begin linking. Navigate the browser to the returned URL; the provider
+     * returns it to hadoku.me/account/link/callback, which completes the link.
+     * Call this only from the user's own click: nothing is fetched from
+     * Discord or Steam before they ask.
+     */
+    startLink: (provider) => send(`/link/${provider}`, "POST", {}),
+    /** 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. */
+    unlink: (provider) => send(`/link/${provider}`, "DELETE"),
+    /** Upload an image (PNG, JPEG, WebP or GIF). It is re-encoded and becomes the chosen source. */
+    upload: (image) => call("/upload", { method: "POST", body: image }),
+    removeUpload: () => send("/upload", "DELETE")
+  };
+}
+async function resolveAvatars(opts, userIds) {
+  const f = opts.fetch ?? fetch;
+  const url = `${opts.baseUrl ?? PREFS_API_BASE}/api/v1/_avatar/resolve`;
+  const unique = [...new Set(userIds)];
+  const out = {};
+  for (let i = 0; i < unique.length; i += RESOLVE_MAX_IDS) {
+    const res = await f(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-User-Key": opts.serviceKey },
+      body: JSON.stringify({ userIds: unique.slice(i, i + RESOLVE_MAX_IDS) })
+    });
+    Object.assign(out, (await readJson(res)).avatars);
+  }
+  return out;
+}
+export {
+  AVATAR_SOURCES,
+  AvatarError,
+  LINK_CALLBACK_PATH,
+  LINK_PROVIDERS,
+  RESOLVE_MAX_IDS,
+  SPRITE_ID_PATTERN,
+  createAvatarClient,
+  resolveAvatars
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hadoku/prefs-client",
-  "version": "1.1.2",
-  "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).",
+  "version": "1.1.3",
+  "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",
   "types": "./dist/index.d.ts",
@@ -17,6 +17,10 @@
     "./games": {
       "types": "./dist/games.d.ts",
       "default": "./dist/games.js"
+    },
+    "./avatar": {
+      "types": "./dist/avatar.d.ts",
+      "default": "./dist/avatar.js"
     }
   },
   "files": [
@@ -45,7 +49,8 @@
     "preferences",
     "prefs",
     "sdk",
-    "game-stats"
+    "game-stats",
+    "avatar"
   ],
   "license": "ISC"
 }