@hadoku/prefs-client 1.1.6 → 1.1.8

package/README.md

@@ -158,10 +158,7 @@ Rules for an app that renders avatars:
 - **`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.
+- 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.

package/dist/service.d.ts

@@ -0,0 +1,49 @@
+interface ServicePrefsOptions {
+    /** The app's namespace: `cardtable` reaches `cardtable` and `cardtable-*`. */
+    app: string;
+    /** The app's service key (on the edge's `prefs-<app>` allow list). */
+    serviceKey: string;
+    /** Default https://hadoku.me/prefs. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+interface ServiceRow<T = Record<string, unknown>> {
+    userId: string;
+    blob: T;
+    version: number;
+    updatedAt: number;
+}
+type ServiceWriteResult<T = Record<string, unknown>> = {
+    ok: true;
+    blob: T;
+    version: number;
+    updatedAt: number;
+}
+/** Someone wrote first; `current` is what is there now. Merge and retry. */
+ | {
+    ok: false;
+    conflict: {
+        blob: T;
+        version: number;
+        updatedAt: number;
+    } | null;
+};
+declare class ServicePrefsError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** prefs-api reads at most this many userIds a call (D1's bind limit). */
+declare const SERVICE_READ_BATCH = 90;
+declare function createServicePrefsClient(opts: ServicePrefsOptions): {
+    /** These people's rows (missing = never written), batched under the read cap. */
+    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>>;
+    /**
+     * 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.
+     */
+    writeFor<T = Record<string, unknown>>(appId: string, userKey: string, patch: Partial<T>, expectedVersion?: number): Promise<ServiceWriteResult<T>>;
+};
+
+export { SERVICE_READ_BATCH, ServicePrefsError, type ServicePrefsOptions, type ServiceRow, type ServiceWriteResult, createServicePrefsClient };

package/dist/service.js

@@ -0,0 +1,92 @@
+// src/constants.ts
+var PREFS_API_BASE = "https://hadoku.me/prefs";
+
+// src/service.ts
+var ServicePrefsError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "ServicePrefsError";
+  }
+  status;
+};
+var SERVICE_READ_BATCH = 90;
+var APP = /^[a-z0-9-]+$/;
+function createServicePrefsClient(opts) {
+  if (!APP.test(opts.app)) throw new Error(`invalid app: ${opts.app}`);
+  const f = opts.fetch ?? fetch;
+  const base = `${opts.baseUrl ?? PREFS_API_BASE}/api/v1/_service/${opts.app}/rows`;
+  const headers = { "Content-Type": "application/json", "X-User-Key": opts.serviceKey };
+  const rowsUrl = (appId) => {
+    if (!APP.test(appId) || appId !== opts.app && !appId.startsWith(`${opts.app}-`)) {
+      throw new Error(`${appId} is not ${opts.app}'s app`);
+    }
+    return `${base}/${appId}`;
+  };
+  async function page(appId, body) {
+    const res = await f(`${rowsUrl(appId)}/read`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) throw await failure(res);
+    return await res.json();
+  }
+  return {
+    /** These people's rows (missing = never written), batched under the read cap. */
+    async read(appId, userIds) {
+      const out = [];
+      for (let i = 0; i < userIds.length; i += SERVICE_READ_BATCH) {
+        out.push(
+          ...(await page(appId, { userIds: userIds.slice(i, i + SERVICE_READ_BATCH) })).rows
+        );
+      }
+      return out;
+    },
+    /** Every person's row in one app, page by page. */
+    async *all(appId, pageSize = 200) {
+      let after = null;
+      do {
+        const p = await page(appId, {
+          limit: pageSize,
+          ...after ? { after } : {}
+        });
+        yield* p.rows;
+        after = p.next;
+      } while (after);
+    },
+    /**
+     * 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.
+     */
+    async writeFor(appId, userKey, patch, expectedVersion) {
+      const res = await f(rowsUrl(appId), {
+        method: "PUT",
+        headers,
+        body: JSON.stringify({
+          userKey,
+          patch,
+          ...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,
+        ...await res.json()
+      };
+    }
+  };
+}
+async function failure(res) {
+  const body = await res.json().catch(() => null);
+  return new ServicePrefsError(res.status, body?.message ?? `HTTP ${res.status}`);
+}
+export {
+  SERVICE_READ_BATCH,
+  ServicePrefsError,
+  createServicePrefsClient
+};

package/package.json

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