castle-web-sdk 0.4.27 → 0.4.28

package/README.md

@@ -416,7 +416,10 @@ const dailyPuzzle = (date.daysSinceCastleEpoch % 30) + 1;
 Returns the signed-in player. Throws `CastleError`
 (`LOGIN_REQUIRED`) when nobody is signed in.
 
-The returned `CastleUser` has `userId`, `username`, `isAnonymous`, and `isActive`.
+A `CastleUser` has `userId`, `username`, `isAnonymous`, `isActive`, `photoUrl`
+(their 256px avatar), `frameUrl` (the 96px frame drawn around it) and `color`
+(the hex their username is shown in); the last three are `null` when unset. The
+urls are `data:` urls, so they go straight into an `<img>` or a texture.
 Anonymous accounts are real logins with generated `anonymous-user-...` names;
 check `isAnonymous` before accepting writes into anything other players see,
 such as a shared gallery.
@@ -426,6 +429,19 @@ const me = await User.getCurrent();
 greet(me.username);
 ```
 
+### `User.get(userId): Promise<CastleUser | null>`
+
+Another player as anyone may see them, or `null` when no such user exists.
+Results are cached per id for the life of the page. The ids come from the
+session's player list or from `Store.user(id)` rows.
+
+```js
+const them = await User.get(player.userId);
+if (them?.photoUrl) {
+  avatar.src = them.photoUrl;
+}
+```
+
 ## Pass
 
 A pass is something a creator sells to players for Castle bricks (the

package/dist/commands.d.ts

@@ -120,6 +120,9 @@ export interface CommandParams {
         score?: number | null;
     };
     "user.getCurrent": Record<string, never>;
+    "user.get": {
+        userId: string;
+    };
     "time.getServerTime": Record<string, never>;
     "pass.has": {
         passId: string;
@@ -214,6 +217,9 @@ export interface CommandResult {
             isAnonymous?: boolean;
         } | null;
     };
+    "user.get": {
+        user: UserPayload | null;
+    };
     "time.getServerTime": {
         timestamp: number;
         timezoneOffset: number;
@@ -254,6 +260,14 @@ export interface CommandResult {
     };
     "lifecycle.restoreState": LifecycleRestoreStateResult;
 }
+export interface UserPayload {
+    userId: string;
+    username: string;
+    isAnonymous: boolean;
+    photoUrl: string | null;
+    frameUrl: string | null;
+    color: string | null;
+}
 export type CommandName = keyof CommandParams;
 export interface SerializedCommandError {
     code: string;

package/dist/user.d.ts

@@ -3,8 +3,12 @@ export interface CastleUser {
     username: string;
     isAnonymous: boolean;
     isActive: boolean;
+    photoUrl: string | null;
+    frameUrl: string | null;
+    color: string | null;
 }
 export interface CastleUserApi {
     getCurrent(): Promise<CastleUser>;
+    get(userId: string): Promise<CastleUser | null>;
 }
 export declare const User: CastleUserApi;

package/dist/user.js

@@ -2,8 +2,12 @@ import { CastleError } from "./errors";
 import { hostRequest } from "./transport";
 let currentUser = null;
 let currentUserPromise = null;
+// Profiles by user id. A profile changes rarely, and a multiplayer deck asks for
+// the same few ids every time a player joins.
+const profiles = new Map();
 export const User = {
     getCurrent,
+    get,
 };
 async function getCurrent() {
     if (currentUser)
@@ -25,15 +29,46 @@ async function fetchCurrentUser() {
         });
     }
     const username = requiredString(user.username, "user.username", operation);
+    const userId = requiredString(user.userId, "user.userId", operation);
+    // The host answers identity from what it already knows. The profile fields
+    // come from the same read `get` does; a host that predates that command
+    // leaves them null.
+    const profile = await get(userId).catch(() => null);
     return {
-        userId: requiredString(user.userId, "user.userId", operation),
+        userId,
         username,
         // A host that predates the flag omits it; anonymous account usernames are
         // always minted as `anonymous-user-<uuid>`, so the prefix is the fallback.
         isAnonymous: user.isAnonymous === true || username.toLowerCase().startsWith("anonymous-user-"),
         isActive: true,
+        photoUrl: profile?.photoUrl ?? null,
+        frameUrl: profile?.frameUrl ?? null,
+        color: profile?.color ?? null,
     };
 }
+// One user by id, or null when no such user exists. Throws `CastleError` on a
+// host that predates the command (`UNKNOWN_COMMAND`).
+async function get(userId) {
+    if (typeof userId !== "string" || userId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "User.get(userId) needs a user id.",
+            operation: "User.get",
+        });
+    }
+    let pending = profiles.get(userId);
+    if (!pending) {
+        pending = fetchProfile(userId);
+        profiles.set(userId, pending);
+        // A failed read is not kept, so the next call asks again.
+        pending.catch(() => profiles.delete(userId));
+    }
+    return pending;
+}
+async function fetchProfile(userId) {
+    const { user } = await hostRequest("user.get", { userId });
+    return user ? { ...user, isActive: true } : null;
+}
 function requiredString(value, field, operation) {
     if (typeof value === "string" && value.length > 0)
         return value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.27",
+  "version": "0.4.28",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",