@hadoku/prefs-client

中文文档
1.1.27发布于 2026/11/13ISCTypeScriptES Module零依赖近 30 天下载 8269

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), the one resolv

原始使用文档
文档目录8 节
  1. Install
  2. Usage
  3. Key behaviours
  4. Capacitor (native APK)
  5. Header-mode (service-to-service, no cookie)
  6. Platform rows ( @wolffm/prefs-client/platform )
  7. Avatars ( @wolffm/prefs-client/avatar )
  8. Avatar cosmetics ( @wolffm/prefs-client/cosmetics )

@wolffm/prefs-client

Client SDK for the hadoku unified preferences store. Wraps hadoku.me/prefs/api/v1/* with localStorage caching, debounced writes, Zod-validated reads, and a React usePrefs() hook.

See docs/planning/unified-prefs-2026-05-20.md for the architectural background.

Install

pnpm add @wolffm/prefs-client zod
# React consumers also:
pnpm add react

Usage

import { z } from 'zod';
import { createPrefsClient } from '@wolffm/prefs-client';
import { usePrefs } from '@wolffm/prefs-client/react';

const TaskPrefsSchema = z.object({
  theme: z.string().optional(),
  themeMode: z.enum(['simple', 'advanced']).optional(),
  alwaysVerticalLayout: z.boolean().optional(),
});

export const taskPrefs = createPrefsClient({
  appId: 'task',
  schema: TaskPrefsSchema,
  defaults: { theme: 'light', themeMode: 'simple' },
  migrations: [
    (blob) => {
      if ('simpleMode' in blob) {
        blob.themeMode = blob.simpleMode ? 'simple' : 'advanced';
        delete blob.simpleMode;
      }
      return blob;
    },
  ],
  bootstrapToSessionStorage: { theme: 'hadoku-theme' },
});

function Settings() {
  const { prefs, save, loading } = usePrefs(taskPrefs);
  if (loading || !prefs) return null;
  return (
    <ThemeToggle
      value={prefs.theme}
      onChange={(t) => save({ theme: t }, { scope: 'device' })}
    />
  );
}

Key behaviours

  • Cache: localStorage at prefs-cache:{userId}:{appId}. Stale-while-revalidate.
  • Writes: 1s-debounced PUT. Multiple save() calls within the window coalesce into one network call.
  • Conflicts: API-Always-Wins. On a 409 the SDK adopts the server blob and re-renders; the local patch is discarded, and the save() (with an explicit expectedVersion) or flush() waiting on it rejects with PrefsConflictError.
  • expectedVersion: by default the SDK sends the last version it has seen (0 before the first read). save(patch, { expectedVersion: n }) sends n; { expectedVersion: null } sends none — last write wins. Both send at once rather than debounced.
  • Cross-tab: BroadcastChannel keyed by prefs:{userId}:{appId} propagates saves between tabs without a server roundtrip.
  • Anon → authed: call client.promoteAnonPrefsToUser() after sign-in. If the server already has user-scope prefs (signed in on another device first), the server wins.
  • Dirty-field protection: a background refresh (or an incoming cross-tab broadcast) never overwrites a field with a save still pending/in-flight — it merges the server/remote blob with your unconfirmed local value instead. Otherwise a refresh landing between an optimistic write and its debounced PUT would visibly revert the change.
  • FOUC bootstrap: bootstrapToSessionStorage mirrors specific fields to sessionStorage so the inline <head> script can apply theme before React mounts. Mirroring only happens on an explicit local save() by default — never on read/hydrate/refresh/broadcast-receive — so an app embedded under a host that owns the same sessionStorage key can't clobber it just by booting. Pass mirrorBootstrapOnRead: true to restore the old every-read mirroring for a key nothing else writes to.

Capacitor (native APK)

Storage is auto-detected: in a native Capacitor webview the SDK reads the Capacitor.Plugins.Preferences global and uses it for the cache; in a browser it uses localStorage. No configuration, no import, and no @capacitor/preferences dependency added to web bundles — the detection is a runtime global read, so web-only consumers are unaffected.

Requirements for the native side:

  • The host APK must have @capacitor/preferences installed (so Capacitor registers the plugin global). The SDK does not bundle or import it.
  • The APK mints its own hadoku_device_id in native storage, separate from the mobile browser's — so the native app and mobile Safari are two distinct devices by design.

You can still override with an explicit adapter (or force one in tests) via createPrefsClient({ storage }). detectStorage() and capacitorStorage() are exported if you want to resolve the adapter yourself.

Pass userKey when there's no hadoku_session cookie to ride (e.g. a CLI or a native app that authenticates with a raw key instead of the cookie):

const client = createPrefsClient({
  appId: 'task-mobile',
  schema: TaskPrefsSchema,
  userKey: process.env.HADOKU_API_KEY,
  // storage auto-detects Capacitor; pass an explicit adapter only to override
});

Platform rows (@wolffm/prefs-client/platform)

Rows that belong to no single app. Import the definition rather than retyping the appId, scope and schema, so the second app to need a setting finds the first one's row instead of inventing its own.

RowFieldsScopeOwner
games (GAMES_ROW)muted, volume (0..1)deviceevery hadoku game: master sound, above a game's own levels
portfoliothemedevice@wolffm/themes; do not write it from an app
import { createPrefsClient } from '@wolffm/prefs-client';
import { GAMES_ROW, GAMES_DEFAULTS } from '@wolffm/prefs-client/platform';

const games = createPrefsClient({ ...GAMES_ROW, defaults: GAMES_DEFAULTS });
await games.save({ muted: true }, { scope: GAMES_ROW.scope });

The profile picture is not a row here: it is ./avatar below, whose fallback is the watchparty character.

Avatars (@wolffm/prefs-client/avatar)

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.

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:

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:

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', name: null }
byUser[id].name; // their live display name, or null for an unknown or closed account

Names come from here too. A server stores only userIds (IDENTITY_MODEL R12) and names people, online or not, when it shows them: resolveAvatars(...)[id].name. Never keep a copy. prefs-api reads the registry at most once a minute per isolate, so a rename shows within a minute and a deleted account stops being named. Over HTTP it is POST /prefs/api/v1/_avatar/resolve { userIds } with a service-tier X-User-Key.

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 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.
  • 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, character choice, linking (linkInPopup: no page navigation), uploads and removal all happen in the settings popout. Don't build your own.

Avatar cosmetics (@wolffm/prefs-client/cosmetics)

What a person wears with their avatar: a name effect, a name gradient, a name font, an avatar overlay (an image the person can move, turn and resize, or a drawn ring or glow), and a message reveal for their chat lines. Items are earned or gifted, never bought; one per slot. People equip them in the settings popout's avatar dialog. Every resolved avatar carries what is worn as cosmetics (ResolvedAvatar.cosmetics, only items the person owns).

import {
  ensureCosmeticsStyles,
  colourStyle,
  nameHtml,
  avatarHtml,
  messageHtml,
} from '@wolffm/prefs-client/cosmetics';

ensureCosmeticsStyles(); // once: the stylesheet, and the clean-up that ends a message reveal
const worn = person.cosmetics; // from resolveAvatars() or the owner's settings
row.style.cssText = colourStyle(character.color); // every text colour derives from this
row.innerHTML =
  avatarHtml({ src: pictureUrl, size: 40, worn }) +
  nameHtml(person.name, worn) +
  messageHtml(text, live ? worn : undefined); // reveal only messages arriving live

Rules for an app that renders them:

  • Colour comes from the character. Put the character's colour in --hc-base on the row (colourStyle). Never give a name effect or gradient its own colour.
  • Reveal live messages only, never history or a scroll-back load. The reveal ends as plain text.
  • Pause what is off screen: toggle hc-idle on rows an IntersectionObserver reports hidden.
  • Leave room for overlays. An overlay may reach about a third of the avatar's size above it and a quarter to each side (PLACEMENT_ZONE); don't clip the avatar's box.
  • Images and fonts load same-origin from /cosmetics/ (hadoku_site public/cosmetics); a font downloads only when someone wears it.
  • Adding an item: COSMETICS in cosmetics-contract.ts, its CSS in cosmetics.ts, an image in public/cosmetics/art/. test/cosmetics.test.ts fails if any of the three is missing, and if a loop animates anything but transform or opacity.

版本与发布记录

@hadoku/prefs-client 共发布 29 个版本,首次发布于 2026/10/28;过去 12 个月发布了 29 个版本。

版本发布日期距今
1.1.27latest2026/11/134 天前
1.1.262026/11/125 天前
1.1.252026/11/116 天前
1.1.242026/11/116 天前
1.1.232026/11/0611 天前
1.1.222026/11/0611 天前

关于 @hadoku/prefs-client 的常见问题

@hadoku/prefs-client 是什么?

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), the one resolv

如何安装 @hadoku/prefs-client?

在项目目录运行 npm install @hadoku/prefs-client,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:zod(^4.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hadoku/prefs-client 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hadoku/prefs-client 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@hadoku/prefs-client 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@hadoku/prefs-client 可以商用吗?

@hadoku/prefs-client 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hadoku/prefs-client 的下载量有多少?

根据 npm 官方下载统计,@hadoku/prefs-client 在 2026/10/17 – 2026/11/15 这 30 天内被下载 8,269 次,日均约 276 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hadoku/prefs-client 还在维护吗?

最新版本 1.1.27 发布于 2026/11/13(4 天前);至今共发布 29 个版本,其中过去 12 个月发布了 29 个;首次发布于 2026/10/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。