castle-web-cli 0.4.118 → 0.4.120

package/dist/api.js

@@ -18,10 +18,21 @@ export async function graphql(query, variables) {
     });
     return res.json();
 }
+// Castle masks every ClientError's message to "Unexpected error." and puts the
+// real one in `extensions.code` -- so the bare message is the same string for a
+// permissions failure, a missing deck, and a bad argument. Carry the code in the
+// message too, since that is all most callers (and the top-level handler) print.
 function handleAPIError(data) {
     if (data?.errors?.length) {
-        const err = new Error(data.errors[0]?.message ?? 'GraphQL error');
-        err.extensions = data.errors[0]?.extensions;
+        const first = data.errors[0];
+        const code = first?.extensions?.code;
+        // `path` names the field that failed, which is the operation for a mutation
+        // -- without it "Unexpected error." doesn't even say which call broke.
+        const where = Array.isArray(first?.path) ? first.path.join('.') : '';
+        const parts = [where, typeof code === 'string' ? code : ''].filter(Boolean);
+        const message = first?.message ?? 'GraphQL error';
+        const err = new Error(parts.length ? `${message} [${parts.join(': ')}]` : message);
+        err.extensions = first?.extensions;
         throw err;
     }
 }

package/dist/castle-host/host.d.ts

@@ -4,11 +4,15 @@
 // Node16 resolution rejects. Mirror the public surface of
 // castle-experimental-web/sdk/src/host.ts; update if that signature changes.
 
+import type { CastleLeaderboardPayload } from './leaderboardPanel.js';
+
 export interface HostContext {
   deckId: string | null;
   sessionId: string | null;
   userId: string | null;
   username: string | null;
+  isAnonymous?: boolean;
+  deepLinkUri?: string | null;
 }
 
 export interface GraphqlError {
@@ -36,6 +40,18 @@ export interface HostCapabilities {
   graphqlFetch: GraphqlFetch;
   platformHandler?: PlatformHandler;
   localPassGrant?: (passId: string) => boolean;
+  showLeaderboard?: (payload: CastleLeaderboardPayload) => void;
+  canShowLeaderboard?: () => boolean;
+  leaderboardShowsParties?: boolean;
+  onStreakCredit?: (credit: LeaderboardStreakCredit) => void;
+  logAnalyticsEvent?: (event: string, properties: Record<string, unknown>) => void;
+}
+
+export interface LeaderboardStreakCredit {
+  deckId: string | null;
+  kind: string;
+  priorStreak: number;
+  newStreak: number;
 }
 
 export interface SerializedCommandError {

package/dist/castle-host/host.js

@@ -1,4 +1,4 @@
-// GENERATED — do not edit. Vendored from castle-experimental-web/sdk/dist/host.js
+// GENERATED — do not edit. Vendored from castle-experimental-web/sdk/dist/
 // Re-run `npm run copy-host` in castle-experimental-web after an SDK change.
 
 // Host-side command executor — the shared module run by every trusted host
@@ -22,6 +22,7 @@ const COMMAND_NAMES = [
     "sharedDeckStorage.update",
     "leaderboard.fetch",
     "leaderboard.save",
+    "leaderboard.show",
     "user.getCurrent",
     "time.getServerTime",
     "pass.has",
@@ -41,6 +42,10 @@ const PLATFORM_COMMAND_NAMES = [
     "portal.prefetch",
     "haptics.play",
 ];
+// Mirrors CASTLE_LEADERBOARD_PAYLOAD_VERSION in leaderboardPanel.ts. Duplicated
+// rather than imported because every import here has to stay type-only; bump
+// both together — the mobile panel ships in app binaries and will skew.
+const LEADERBOARD_PAYLOAD_VERSION = 1;
 function isCommandName(value) {
     return (typeof value === "string" &&
         COMMAND_NAMES.includes(value));
@@ -94,9 +99,11 @@ function runCommand(ctx, command, params, caps) {
         case "sharedDeckStorage.update":
             return sharedDeckStorageUpdate(ctx, params, gql);
         case "leaderboard.fetch":
-            return leaderboardFetch(ctx, params, gql);
+            return leaderboardFetch(ctx, params, caps);
         case "leaderboard.save":
-            return leaderboardSave(ctx, params, gql);
+            return leaderboardSave(ctx, params, caps);
+        case "leaderboard.show":
+            return leaderboardShow(ctx, params, caps);
         case "user.getCurrent":
             return Promise.resolve(userGetCurrent(ctx));
         case "time.getServerTime":
@@ -275,12 +282,12 @@ async function sharedDeckStorageUpdate(ctx, params, gql) {
     await graphql(gql, UPDATE_SHARED_DECK_STORAGE_MUTATION, { deckId, sessionId: ctx.sessionId, userId, updates: asUpdates(params.updates) }, "sharedDeckStorage.update");
     return { ok: true };
 }
-async function leaderboardFetch(ctx, params, gql) {
+async function leaderboardFetch(ctx, params, caps) {
     const deckId = requireDeckId(ctx, "leaderboard.fetch");
     const variables = {
         deckId,
         variable: asString(params.variable, "variable", "leaderboard.fetch"),
-        type: asLeaderboardType(params.type),
+        type: asLeaderboardType(params.type, "leaderboard.fetch"),
         filter: "dedupUsers",
         includeFollowList: false,
         includeParties: false,
@@ -292,22 +299,147 @@ async function leaderboardFetch(ctx, params, gql) {
     // No score → plain read of the settled leaderboard.
     const score = asOptionalNumber(params.score);
     if (score !== null) {
-        const data = await graphql(gql, LEADERBOARD_V2_MUTATION, { ...variables, score }, "leaderboard.fetch");
+        const data = await graphql(caps.graphqlFetch, LEADERBOARD_V2_MUTATION, { ...variables, score }, "leaderboard.fetch");
+        relayStreakCredit(caps, deckId, data.leaderboardV2?.streakCredit);
         return { leaderboard: data.leaderboardV2, currentUserId: ctx.userId };
     }
-    const data = await graphql(gql, LEADERBOARD_QUERY, variables, "leaderboard.fetch");
+    const data = await graphql(caps.graphqlFetch, LEADERBOARD_QUERY, variables, "leaderboard.fetch");
     return { leaderboard: data.leaderboard, currentUserId: ctx.userId };
 }
-async function leaderboardSave(ctx, params, gql) {
+async function leaderboardSave(ctx, params, caps) {
     const deckId = requireDeckId(ctx, "leaderboard.save");
-    await graphql(gql, SAVE_LEADERBOARD_MUTATION, {
+    // saveVariableToLeaderboard returns a Json scalar shaped { streakCredit },
+    // so there is no selection set to add — read the key off the scalar.
+    const data = await graphql(caps.graphqlFetch, SAVE_LEADERBOARD_MUTATION, {
         deckId,
         variable: asString(params.variable, "variable", "leaderboard.save"),
         score: asNumber(params.score, "score", "leaderboard.save"),
         scope: asOptionalString(params.scope) ?? null,
     }, "leaderboard.save");
+    relayStreakCredit(caps, deckId, data.saveVariableToLeaderboard?.streakCredit);
     return { ok: true };
 }
+// The host renders the board itself, so nothing here flows back to the deck
+// beyond whether it was presented. With a score this is the same write-and-read
+// the classic leaderboard performs when it opens.
+async function leaderboardShow(ctx, params, caps) {
+    const show = caps.showLeaderboard;
+    if (!show)
+        return { status: "unavailable" };
+    if (caps.canShowLeaderboard && !caps.canShowLeaderboard()) {
+        return { status: "unavailable" };
+    }
+    const deckId = requireDeckId(ctx, "leaderboard.show");
+    const variable = asString(params.variable, "variable", "leaderboard.show");
+    const type = asLeaderboardType(params.type, "leaderboard.show");
+    const scope = asOptionalString(params.scope) ?? null;
+    const label = asOptionalString(params.label) ?? "Score";
+    const empty = {
+        v: LEADERBOARD_PAYLOAD_VERSION,
+        deckId,
+        variable,
+        scope,
+        type,
+        label,
+        isAnonymous: ctx.isAnonymous === true,
+        showParties: caps.leaderboardShowsParties === true,
+        yourScore: null,
+        list: [],
+        followList: [],
+        parties: [],
+    };
+    // Present, then fetch. The round trip is the slow part of an open, so the
+    // board goes up on its spinner the moment the deck asks for it and fills in
+    // when the rows land — the same order the engine's leaderboard uses.
+    show({ ...empty, loading: true });
+    let raw;
+    try {
+        raw = await fetchFullLeaderboard(caps, {
+            deckId,
+            variable,
+            type,
+            scope,
+            label,
+            url: ctx.deepLinkUri ?? null,
+            score: asOptionalNumber(params.score),
+        });
+    }
+    catch (error) {
+        // The board is already up: leave it on an empty list rather than a spinner
+        // that never stops. The deck still gets the error.
+        show(empty);
+        throw error;
+    }
+    relayStreakCredit(caps, deckId, raw?.streakCredit);
+    show({
+        ...empty,
+        yourScore: asNumberish(raw?.yourScore?.score),
+        list: leaderboardRows(raw?.list),
+        followList: leaderboardRows(raw?.followList),
+        parties: leaderboardParties(raw?.parties),
+    });
+    caps.logAnalyticsEvent?.("VIEW_LEADERBOARD", {
+        deckId,
+        variableName: variable,
+        scope: scope ?? "",
+        leaderboardType: type,
+    });
+    return { status: "shown" };
+}
+// A buffered score turns the read into the engine's write-and-read, so the
+// player's own result is on the board the first time they see it.
+function fetchFullLeaderboard(caps, request) {
+    const { score, ...rest } = request;
+    const variables = {
+        ...rest,
+        filter: "dedupUsers",
+        includeFollowList: true,
+        includeParties: true,
+    };
+    if (score === null) {
+        return graphql(caps.graphqlFetch, LEADERBOARD_FULL_QUERY, variables, "leaderboard.show").then((data) => data.leaderboard);
+    }
+    return graphql(caps.graphqlFetch, LEADERBOARD_V2_FULL_MUTATION, { ...variables, score }, "leaderboard.show").then((data) => data.leaderboardV2);
+}
+function relayStreakCredit(caps, deckId, credit) {
+    const kind = credit?.kind;
+    if (!caps.onStreakCredit || typeof kind !== "string" || kind.length === 0)
+        return;
+    caps.onStreakCredit({
+        deckId,
+        kind,
+        priorStreak: asNumberish(credit?.priorStreak) ?? 0,
+        newStreak: asNumberish(credit?.newStreak) ?? 0,
+    });
+}
+function leaderboardRows(entries) {
+    return (entries ?? []).map((entry) => ({
+        place: asNumberish(entry?.place),
+        score: entry?.score === null || entry?.score === undefined ? "" : String(entry.score),
+        isDeckCreator: entry?.isDeckCreator === true,
+        isLinkSharer: entry?.isLinkSharer === true,
+        isRequiredUser: entry?.isRequiredUser === true,
+        user: {
+            userId: asOptionalString(entry?.user?.userId),
+            username: asOptionalString(entry?.user?.username),
+            isAnonymous: entry?.user?.isAnonymous === true,
+            color: asOptionalString(entry?.user?.usernameStyle?.color),
+            avatarUrl: asOptionalString(entry?.user?.photo?.smallAvatarUrl),
+            badgeUrl: asOptionalString(entry?.user?.usernameBadge?.smallBadgeUrl),
+            frameUrl: asOptionalString(entry?.user?.photoFrame?.smallFrameUrl),
+        },
+    }));
+}
+function leaderboardParties(parties) {
+    return (parties ?? []).map((party) => ({
+        partyId: asOptionalString(party?.partyId),
+        name: asOptionalString(party?.name) ?? "",
+        avatarUrls: (party?.highlightUsers ?? [])
+            .map((user) => asOptionalString(user?.photo?.smallAvatarUrl))
+            .filter((url) => url !== null),
+        lastMessageTime: asOptionalString(party?.chatChannel?.lastChatMessageForDeck?.createdTime),
+    }));
+}
 function userGetCurrent(ctx) {
     if (!ctx.userId || !ctx.username)
         return { user: null };
@@ -381,10 +513,10 @@ function asScope(value, command) {
         return value;
     throw new HostCommandError("CASTLE_STORAGE_INVALID_SCOPE", 'SharedStorage scope must be "deck" or "user".', command);
 }
-function asLeaderboardType(value) {
+function asLeaderboardType(value, command) {
     if (value === "high" || value === "low")
         return value;
-    throw new HostCommandError("INVALID_LEADERBOARD_TYPE", "Leaderboard type must be high or low.", "leaderboard.fetch");
+    throw new HostCommandError("INVALID_LEADERBOARD_TYPE", "Leaderboard type must be high or low.", command);
 }
 function asString(value, field, command) {
     if (typeof value === "string" && value.length > 0)
@@ -402,6 +534,16 @@ function asOptionalString(value) {
 function asOptionalNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+// GraphQL hands numeric fields back as numbers or as strings depending on the
+// scalar, so leaderboard payload shaping accepts both.
+function asNumberish(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value !== "string")
+        return null;
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
 const DECK_STORAGE_QUERY = `
   query CastleDeckStorage($deckId: ID!, $sessionId: ID) {
     deckStorage(deckId: $deckId, sessionId: $sessionId)
@@ -507,8 +649,104 @@ const LEADERBOARD_V2_MUTATION = `
           username
         }
       }
+      streakCredit { kind priorStreak newStreak }
+    }
+  }
+`;
+// The selection the host's own leaderboard UI renders from: the engine's full
+// one (core/src/leaderboards.cpp getLeaderboard), which is a superset of the
+// deck-facing one above. It is the only net-new artifact of `leaderboard.show`
+// — the query text; every behavioural decision stays in the SDK's one copy.
+const LEADERBOARD_FULL_FIELDS = `
+  parties {
+    partyId
+    status
+    userIds
+    name
+    users {
+      userId
+      username
+      usernameStyle { color }
+      usernameBadge { smallBadgeUrl }
+      photo { smallAvatarUrl }
+    }
+    highlightUsers {
+      userId
+      photo { smallAvatarUrl }
+    }
+    chatChannel {
+      chatChannelId
+      lastChatMessageForDeck {
+        createdTime
+        fromUser { userId }
+      }
     }
   }
+  yourScore { score }
+  list {
+    place
+    score
+    isDeckCreator
+    isLinkSharer
+    user {
+      userId
+      username
+      usernameStyle { color }
+      usernameBadge { smallBadgeUrl }
+      isAnonymous
+      photoFrame { smallFrameUrl }
+      photo { smallAvatarUrl }
+    }
+  }
+  followList {
+    place
+    score
+    isRequiredUser
+    isDeckCreator
+    isLinkSharer
+    user {
+      userId
+      username
+      usernameStyle { color }
+      usernameBadge { smallBadgeUrl }
+      isAnonymous
+      photoFrame { smallFrameUrl }
+      photo { smallAvatarUrl }
+    }
+  }
+  streakCredit { kind priorStreak newStreak }
+`;
+const LEADERBOARD_FULL_ARGS = `
+  deckId: $deckId
+  variable: $variable
+  type: $type
+  filter: $filter
+  label: $label
+  includeFollowList: $includeFollowList
+  includeParties: $includeParties
+  scope: $scope
+  url: $url
+`;
+const LEADERBOARD_FULL_VARS = `
+  $deckId: ID!
+  $variable: String!
+  $type: LeaderboardType!
+  $filter: LeaderboardFilter!
+  $label: String
+  $includeFollowList: Boolean
+  $includeParties: Boolean
+  $scope: String
+  $url: String
+`;
+const LEADERBOARD_FULL_QUERY = `
+  query CastleLeaderboardFull(${LEADERBOARD_FULL_VARS}) {
+    leaderboard(${LEADERBOARD_FULL_ARGS}) {${LEADERBOARD_FULL_FIELDS}}
+  }
+`;
+const LEADERBOARD_V2_FULL_MUTATION = `
+  mutation CastleLeaderboardV2Full(${LEADERBOARD_FULL_VARS}, $score: Float!) {
+    leaderboardV2(${LEADERBOARD_FULL_ARGS}, score: $score) {${LEADERBOARD_FULL_FIELDS}}
+  }
 `;
 const SAVE_LEADERBOARD_MUTATION = `
   mutation CastleSaveVariableToLeaderboard(

package/dist/castle-host/leaderboardPanel.d.ts

@@ -0,0 +1,73 @@
+// Hand-written declaration for the vendored, self-contained leaderboardPanel.js
+// (runtime copied here by castle-experimental-web/scripts/copy-host-module.mjs).
+// Kept tiny and import-free on purpose. TypeScript pairs this with the sibling
+// .js automatically. Mirror the public surface of
+// castle-experimental-web/sdk/src/leaderboardPanel.ts; update if it changes.
+
+export declare const CASTLE_LEADERBOARD_PAYLOAD_VERSION: number;
+
+export type CastleLeaderboardTab = 'global' | 'forYou';
+
+export interface CastleLeaderboardUser {
+  userId: string | null;
+  username: string | null;
+  isAnonymous: boolean;
+  color: string | null;
+  avatarUrl: string | null;
+  badgeUrl: string | null;
+  frameUrl: string | null;
+}
+
+export interface CastleLeaderboardRow {
+  place: number | null;
+  score: string;
+  isDeckCreator: boolean;
+  isLinkSharer: boolean;
+  isRequiredUser: boolean;
+  user: CastleLeaderboardUser;
+}
+
+export interface CastleLeaderboardParty {
+  partyId: string | null;
+  name: string;
+  avatarUrls: string[];
+  lastMessageTime: string | null;
+}
+
+export interface CastleLeaderboardPayload {
+  v: number;
+  deckId: string | null;
+  variable: string;
+  scope: string | null;
+  type: 'high' | 'low';
+  label: string;
+  isAnonymous: boolean;
+  showParties: boolean;
+  // Set while the host has put the board up but its rows haven't landed yet.
+  loading?: boolean;
+  yourScore: number | null;
+  list: CastleLeaderboardRow[];
+  followList: CastleLeaderboardRow[];
+  parties: CastleLeaderboardParty[];
+}
+
+export type CastleLeaderboardEvent =
+  | { type: 'ready' }
+  | { type: 'close' }
+  | { type: 'share' }
+  | { type: 'openProfile'; userId: string | null; username: string | null }
+  | { type: 'savePrompt'; userId: string | null }
+  | { type: 'switchTab'; tab: CastleLeaderboardTab };
+
+export interface CastleLeaderboardPanel {
+  render(payload: CastleLeaderboardPayload): void;
+  clear(): void;
+  destroy(): void;
+}
+
+export declare function mountCastleLeaderboardPanel(
+  root: HTMLElement,
+  onEvent: (event: CastleLeaderboardEvent) => void
+): CastleLeaderboardPanel;
+
+export declare function castleLeaderboardPanelPageBootstrap(): void;