@hadoku/prefs-client 1.1.9 → 1.1.11

package/README.md

@@ -147,9 +147,16 @@ const byUser = await resolveAvatars(
   { serviceKey: process.env.SERVICE_KEY! },
   userIds
 );
-// every requested id is present; unknown users resolve to { source: 'sprite' }
+// 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

package/dist/avatar.d.ts

@@ -93,9 +93,18 @@ interface LinkStart {
 interface ResolveRequest {
     userIds: string[];
 }
+/**
+ * One person as a server shows them: their avatar and their live display name.
+ * `name` is null for an unknown id or a closed (deleted, banned) account, so a
+ * server that stores only userIds (IDENTITY_MODEL R12) names people at display
+ * time and never keeps a copy.
+ */
+interface ResolvedPerson extends ResolvedAvatar {
+    name: string | null;
+}
 interface ResolveResponse {
-    /** Every requested id is present; an unknown user resolves to `{ source: 'sprite' }`. */
-    avatars: Record<string, ResolvedAvatar>;
+    /** Every requested id is present; an unknown user resolves to `{ source: 'sprite', name: null }`. */
+    avatars: Record<string, ResolvedPerson>;
 }
 declare const RESOLVE_MAX_IDS = 100;
 /** A watchparty character id, as prefs-api accepts one from the watchparty blob. */
@@ -156,9 +165,11 @@ interface ResolveAvatarsOptions extends AvatarClientOptions {
     serviceKey: string;
 }
 /**
- * Server-side: resolve many users' avatars by userId. Batches past
+ * Server-side: resolve many users by userId: each one's avatar and live display
+ * `name` (null for an unknown or closed account). Store only the userId and
+ * call this when showing people (IDENTITY_MODEL R12). 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>>;
+declare function resolveAvatars(opts: ResolveAvatarsOptions, userIds: readonly string[]): Promise<Record<string, ResolvedPerson>>;
 
-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 };
+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, type ResolvedPerson, SPRITE_ID_PATTERN, type UploadView, createAvatarClient, resolveAvatars };

package/dist/items.d.ts

@@ -0,0 +1,37 @@
+interface Item<T = unknown> {
+    key: string;
+    value: T;
+    version: number;
+    updatedAt: number;
+}
+type ItemWriteResult<T = unknown> = {
+    ok: true;
+    item: Item<T>;
+}
+/** Someone wrote first (or `expectedVersion: 0` and it exists): `current` is what is there. */
+ | {
+    ok: false;
+    conflict: Item<T> | null;
+};
+declare class ItemsError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+interface ItemsClientOptions {
+    appId: string;
+    /** The person's key, as the edge forwarded it. Omit in a browser (cookie). */
+    userKey?: string;
+    /** Default https://hadoku.me/prefs. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+declare function createItemsClient(opts: ItemsClientOptions): {
+    get<T = unknown>(key: string): Promise<Item<T> | null>;
+    /** Every item under `prefix`, following pages. */
+    list<T = unknown>(prefix?: string): Promise<Item<T>[]>;
+    /** Replace one item. `expectedVersion` refuses a lost update; 0 means "only if absent". */
+    put<T = unknown>(key: string, value: T, expectedVersion?: number): Promise<ItemWriteResult<T>>;
+    delete(key: string): Promise<boolean>;
+};
+
+export { type Item, type ItemWriteResult, type ItemsClientOptions, ItemsError, createItemsClient };

package/dist/items.js

@@ -0,0 +1,76 @@
+// src/constants.ts
+var PREFS_API_BASE = "https://hadoku.me/prefs";
+
+// src/items.ts
+var ItemsError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "ItemsError";
+  }
+  status;
+};
+var APP = /^[a-z0-9-]+$/;
+function createItemsClient(opts) {
+  if (!APP.test(opts.appId)) throw new Error(`invalid appId: ${opts.appId}`);
+  const f = opts.fetch ?? fetch;
+  const base = `${opts.baseUrl ?? PREFS_API_BASE}/api/v1/${opts.appId}/items`;
+  const headers = {
+    "Content-Type": "application/json",
+    ...opts.userKey ? { "X-User-Key": opts.userKey } : {}
+  };
+  const url = (key) => `${base}/${encodeURIComponent(key)}`;
+  return {
+    async get(key) {
+      const res = await f(url(key), { headers, credentials: "same-origin" });
+      if (res.status === 404) return null;
+      if (!res.ok) throw await failure(res);
+      return await res.json();
+    },
+    /** Every item under `prefix`, following pages. */
+    async list(prefix = "") {
+      const out = [];
+      let after = null;
+      do {
+        const q = new URLSearchParams({ prefix, limit: "500", ...after ? { after } : {} });
+        const res = await f(`${base}?${q}`, { headers, credentials: "same-origin" });
+        if (!res.ok) throw await failure(res);
+        const page = await res.json();
+        out.push(...page.items);
+        after = page.next;
+      } while (after);
+      return out;
+    },
+    /** Replace one item. `expectedVersion` refuses a lost update; 0 means "only if absent". */
+    async put(key, value, expectedVersion) {
+      const res = await f(url(key), {
+        method: "PUT",
+        headers,
+        credentials: "same-origin",
+        body: JSON.stringify({
+          value,
+          ...expectedVersion !== void 0 ? { expectedVersion } : {}
+        })
+      });
+      if (res.status === 409) {
+        const body = await res.json().catch(() => null);
+        return { ok: false, conflict: body?.current ?? null };
+      }
+      if (!res.ok) throw await failure(res);
+      return { ok: true, item: await res.json() };
+    },
+    async delete(key) {
+      const res = await f(url(key), { method: "DELETE", headers, credentials: "same-origin" });
+      if (!res.ok) throw await failure(res);
+      return (await res.json()).deleted;
+    }
+  };
+}
+async function failure(res) {
+  const body = await res.json().catch(() => null);
+  return new ItemsError(res.status, body?.message ?? body?.error ?? `HTTP ${res.status}`);
+}
+export {
+  ItemsError,
+  createItemsClient
+};

package/dist/service.d.ts

@@ -1,3 +1,5 @@
+import { Item, ItemWriteResult } from './items.js';
+
 interface ServicePrefsOptions {
     /** The app's namespace: `cardtable` reaches `cardtable` and `cardtable-*`. */
     app: string;
@@ -39,6 +41,18 @@ declare function createServicePrefsClient(opts: ServicePrefsOptions): {
     read<T = Record<string, unknown>>(appId: string, userIds: readonly string[]): Promise<ServiceRow<T>[]>;
     /** Every person's row in one app, page by page. */
     all<T = Record<string, unknown>>(appId: string, pageSize?: number): AsyncGenerator<ServiceRow<T>>;
+    /** Items across people (these userIds, ≤90 a call, or everyone), under an optional prefix. */
+    readItems<T = unknown>(appId: string, opts?: {
+        userIds?: readonly string[];
+        prefix?: string;
+    }): Promise<(Item<T> & {
+        userId: string;
+    })[]>;
+    /** Write one of a person's items, the person named by their own live key. */
+    writeItemFor<T = unknown>(appId: string, userKey: string, key: string, value: T, expectedVersion?: number): Promise<ItemWriteResult<T>>;
+    deleteItemFor(appId: string, userKey: string, key: string): Promise<boolean>;
+    /** Delete EVERY person's items under a non-empty prefix (a deleted set, say). */
+    deleteItemsAcross(appId: string, prefix: string): Promise<number>;
     /**
      * Shallow-merge `patch` into the person's row, the person named by their
      * own live key. Pass the `expectedVersion` you read to refuse a lost update.

package/dist/service.js

@@ -23,6 +23,11 @@ function createServicePrefsClient(opts) {
     }
     return `${base}/${appId}`;
   };
+  const itemsBase = `${opts.baseUrl ?? PREFS_API_BASE}/api/v1/_service/${opts.app}/items`;
+  const itemsUrl = (appId) => {
+    rowsUrl(appId);
+    return `${itemsBase}/${appId}`;
+  };
   async function page(appId, body) {
     const res = await f(`${rowsUrl(appId)}/read`, {
       method: "POST",
@@ -55,6 +60,67 @@ function createServicePrefsClient(opts) {
         after = p.next;
       } while (after);
     },
+    /** Items across people (these userIds, ≤90 a call, or everyone), under an optional prefix. */
+    async readItems(appId, opts2 = {}) {
+      const out = [];
+      const batches = opts2.userIds ? Array.from(
+        { length: Math.ceil(opts2.userIds.length / SERVICE_READ_BATCH) },
+        (_, i) => opts2.userIds.slice(i * SERVICE_READ_BATCH, (i + 1) * SERVICE_READ_BATCH)
+      ) : [void 0];
+      for (const userIds of batches) {
+        if (userIds && userIds.length === 0) continue;
+        let after = null;
+        do {
+          const res = await f(`${itemsUrl(appId)}/read`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ userIds, prefix: opts2.prefix, after, limit: 500 })
+          });
+          if (!res.ok) throw await failure(res);
+          const page2 = await res.json();
+          out.push(...page2.items);
+          after = page2.next;
+        } while (after);
+      }
+      return out;
+    },
+    /** Write one of a person's items, the person named by their own live key. */
+    async writeItemFor(appId, userKey, key, value, expectedVersion) {
+      const res = await f(`${itemsUrl(appId)}/${encodeURIComponent(key)}`, {
+        method: "PUT",
+        headers,
+        body: JSON.stringify({
+          userKey,
+          value,
+          ...expectedVersion !== void 0 ? { expectedVersion } : {}
+        })
+      });
+      if (res.status === 409) {
+        const body = await res.json().catch(() => null);
+        return { ok: false, conflict: body?.current ?? null };
+      }
+      if (!res.ok) throw await failure(res);
+      return { ok: true, item: await res.json() };
+    },
+    async deleteItemFor(appId, userKey, key) {
+      const res = await f(`${itemsUrl(appId)}/${encodeURIComponent(key)}`, {
+        method: "DELETE",
+        headers,
+        body: JSON.stringify({ userKey })
+      });
+      if (!res.ok) throw await failure(res);
+      return (await res.json()).deleted;
+    },
+    /** Delete EVERY person's items under a non-empty prefix (a deleted set, say). */
+    async deleteItemsAcross(appId, prefix) {
+      const res = await f(`${itemsUrl(appId)}/delete-across`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ prefix })
+      });
+      if (!res.ok) throw await failure(res);
+      return (await res.json()).deleted;
+    },
     /**
      * Shallow-merge `patch` into the person's row, the person named by their
      * own live key. Pass the `expectedVersion` you read to refuse a lost update.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadoku/prefs-client",
-  "version": "1.1.9",
+  "version": "1.1.11",
   "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",
@@ -29,6 +29,10 @@
     "./service": {
       "types": "./dist/service.d.ts",
       "default": "./dist/service.js"
+    },
+    "./items": {
+      "types": "./dist/items.d.ts",
+      "default": "./dist/items.js"
     }
   },
   "files": [