castle-web-sdk 0.4.0 → 0.4.2

package/src/leaderboard.ts

@@ -0,0 +1,456 @@
+import { getAuth, requireAuthToken } from "./auth";
+import { isEdit, requireDeckId } from "./context";
+import { CastleError } from "./errors";
+import { graphqlRequest, type GraphqlVariables } from "./graphql";
+
+export type LeaderboardSort = "high" | "low";
+export type LeaderboardScope = string;
+
+export interface LeaderboardOptions {
+  scope?: LeaderboardScope | null;
+}
+
+export interface LeaderboardEntry {
+  place: number;
+  value: number;
+  username: string;
+  userId?: string;
+}
+
+export interface LeaderboardData {
+  list: LeaderboardEntry[];
+  playerRank?: number;
+  playerValue?: number;
+}
+
+interface LeaderboardRequest {
+  deckId: string;
+  variable: string;
+  type: LeaderboardSort;
+  scope: string | null;
+  token: string;
+  userId: string | null;
+}
+
+interface PendingLeaderboardWrite {
+  deckId: string;
+  variable: string;
+  scope: string | null;
+  highScore: number;
+  lowScore: number;
+  isHighDirty: boolean;
+  isLowDirty: boolean;
+}
+
+interface LeaderboardWriteJob {
+  record: PendingLeaderboardWrite;
+  type: "high" | "low" | "both";
+  score: number;
+}
+
+interface GraphqlLeaderboardUser {
+  userId?: string | null;
+  username?: string | null;
+}
+
+interface GraphqlLeaderboardEntry {
+  place?: string | number | null;
+  score?: string | number | null;
+  user?: GraphqlLeaderboardUser | null;
+}
+
+interface GraphqlLeaderboard {
+  list?: GraphqlLeaderboardEntry[] | null;
+  yourScore?: GraphqlLeaderboardEntry | null;
+}
+
+interface LeaderboardQueryData {
+  leaderboard: GraphqlLeaderboard;
+}
+
+interface SaveLeaderboardData {
+  saveVariableToLeaderboard: null;
+}
+
+const LEADERBOARD_FLUSH_INTERVAL_MS = 5000;
+
+const leaderboardWrites = new Map<string, PendingLeaderboardWrite>();
+let leaderboardFlushTimer: ReturnType<typeof setTimeout> | null = null;
+let leaderboardFlushPromise: Promise<void> | null = null;
+let leaderboardUnloadHooked = false;
+
+export const Leaderboard = {
+  write(
+    variable: string,
+    score: number,
+    options: LeaderboardOptions = {},
+  ): void {
+    writeLeaderboard(variable, score, options);
+  },
+
+  fetch(
+    variable: string,
+    type: LeaderboardSort,
+    options: LeaderboardOptions = {},
+  ): Promise<LeaderboardData> {
+    return fetchLeaderboardData(variable, type, options);
+  },
+} as const;
+
+function writeLeaderboard(
+  variable: string,
+  score: number,
+  options: LeaderboardOptions,
+): void {
+  if (isEdit()) return;
+  void bufferLeaderboardWrite(variable, score, options).catch(
+    reportLeaderboardError,
+  );
+}
+
+async function fetchLeaderboardData(
+  variable: string,
+  type: LeaderboardSort,
+  options: LeaderboardOptions,
+): Promise<LeaderboardData> {
+  const request = await leaderboardRequest(
+    "Leaderboard.fetch",
+    variable,
+    type,
+    options,
+  );
+  return normalizeLeaderboard(await fetchLeaderboard(request), request.userId);
+}
+
+async function bufferLeaderboardWrite(
+  variable: string,
+  score: number,
+  options: LeaderboardOptions,
+): Promise<void> {
+  assertLeaderboardVariable(variable, "Leaderboard.write");
+  assertLeaderboardScore(score, "Leaderboard.write");
+  const deckId = await requireDeckId("Leaderboard.write");
+  await requireAuthToken("Leaderboard.write");
+  const scope = leaderboardScope(options);
+  const key = leaderboardWriteKey(deckId, variable, scope);
+  const record = leaderboardWrites.get(key);
+  if (record) {
+    updatePendingLeaderboardWrite(record, score);
+  } else {
+    leaderboardWrites.set(
+      key,
+      newPendingLeaderboardWrite(deckId, variable, scope, score),
+    );
+  }
+  ensureLeaderboardUnloadFlush();
+  scheduleLeaderboardFlush();
+}
+
+function newPendingLeaderboardWrite(
+  deckId: string,
+  variable: string,
+  scope: string | null,
+  score: number,
+): PendingLeaderboardWrite {
+  return {
+    deckId,
+    variable,
+    scope,
+    highScore: score,
+    lowScore: score,
+    isHighDirty: true,
+    isLowDirty: true,
+  };
+}
+
+function updatePendingLeaderboardWrite(
+  record: PendingLeaderboardWrite,
+  score: number,
+): void {
+  if (score > record.highScore) {
+    record.highScore = score;
+    record.isHighDirty = true;
+  }
+  if (score < record.lowScore) {
+    record.lowScore = score;
+    record.isLowDirty = true;
+  }
+}
+
+function scheduleLeaderboardFlush(): void {
+  if (leaderboardFlushTimer) return;
+  leaderboardFlushTimer = setTimeout(() => {
+    leaderboardFlushTimer = null;
+    void flushLeaderboardWrites().catch(reportLeaderboardError);
+  }, LEADERBOARD_FLUSH_INTERVAL_MS);
+}
+
+function ensureLeaderboardUnloadFlush(): void {
+  if (leaderboardUnloadHooked || typeof window === "undefined") return;
+  leaderboardUnloadHooked = true;
+  window.addEventListener("pagehide", () => {
+    void flushLeaderboardWrites().catch(reportLeaderboardError);
+  });
+}
+
+async function flushLeaderboardWrites(): Promise<void> {
+  if (leaderboardFlushPromise) return leaderboardFlushPromise;
+  leaderboardFlushPromise = flushLeaderboardWritesOnce().finally(() => {
+    leaderboardFlushPromise = null;
+    if (hasDirtyLeaderboardWrites()) scheduleLeaderboardFlush();
+  });
+  return leaderboardFlushPromise;
+}
+
+async function flushLeaderboardWritesOnce(): Promise<void> {
+  const jobs = leaderboardWriteJobs();
+  if (jobs.length === 0) return;
+  const token = await requireAuthToken("Leaderboard.write");
+  for (const job of jobs) {
+    await saveLeaderboardScore(job.record, job.score, token);
+    markLeaderboardWriteClean(job);
+  }
+}
+
+function leaderboardWriteJobs(): LeaderboardWriteJob[] {
+  const jobs: LeaderboardWriteJob[] = [];
+  for (const record of leaderboardWrites.values()) {
+    if (
+      record.isHighDirty &&
+      record.isLowDirty &&
+      record.highScore === record.lowScore
+    ) {
+      jobs.push({ record, type: "both", score: record.highScore });
+    } else {
+      if (record.isHighDirty)
+        jobs.push({ record, type: "high", score: record.highScore });
+      if (record.isLowDirty)
+        jobs.push({ record, type: "low", score: record.lowScore });
+    }
+  }
+  return jobs;
+}
+
+function markLeaderboardWriteClean(job: LeaderboardWriteJob): void {
+  const { record, score, type } = job;
+  if ((type === "high" || type === "both") && record.highScore === score) {
+    record.isHighDirty = false;
+  }
+  if ((type === "low" || type === "both") && record.lowScore === score) {
+    record.isLowDirty = false;
+  }
+}
+
+function hasDirtyLeaderboardWrites(): boolean {
+  for (const record of leaderboardWrites.values()) {
+    if (record.isHighDirty || record.isLowDirty) return true;
+  }
+  return false;
+}
+
+async function leaderboardRequest(
+  operation: string,
+  variable: string,
+  type: LeaderboardSort,
+  options: LeaderboardOptions,
+): Promise<LeaderboardRequest> {
+  assertLeaderboardVariable(variable, operation);
+  assertLeaderboardType(type, operation);
+  const [deckId, token, auth] = await Promise.all([
+    requireDeckId(operation),
+    requireAuthToken(operation),
+    getAuth(),
+  ]);
+  return {
+    deckId,
+    variable,
+    type,
+    scope: leaderboardScope(options),
+    token,
+    userId: auth.userId ?? null,
+  };
+}
+
+async function fetchLeaderboard(
+  request: LeaderboardRequest,
+): Promise<GraphqlLeaderboard> {
+  const data = await graphqlRequest<LeaderboardQueryData>(
+    `
+      query CastleLeaderboard(
+        $deckId: ID!
+        $variable: String!
+        $type: LeaderboardType!
+        $filter: LeaderboardFilter!
+        $includeFollowList: Boolean
+        $includeParties: Boolean
+        $scope: String
+      ) {
+        leaderboard(
+          deckId: $deckId
+          variable: $variable
+          type: $type
+          filter: $filter
+          includeFollowList: $includeFollowList
+          includeParties: $includeParties
+          scope: $scope
+        ) ${leaderboardFields()}
+      }
+    `,
+    leaderboardVariables(request),
+    {
+      operation: "CastleLeaderboard",
+      token: request.token,
+      requireAuth: true,
+    },
+  );
+  return data.leaderboard;
+}
+
+async function saveLeaderboardScore(
+  record: PendingLeaderboardWrite,
+  score: number,
+  token: string,
+): Promise<void> {
+  await graphqlRequest<SaveLeaderboardData>(
+    `
+      mutation CastleSaveVariableToLeaderboard(
+        $deckId: ID!
+        $variable: String!
+        $score: Float!
+        $scope: String
+      ) {
+        saveVariableToLeaderboard(
+          deckId: $deckId
+          variable: $variable
+          score: $score
+          scope: $scope
+        )
+      }
+    `,
+    {
+      deckId: record.deckId,
+      variable: record.variable,
+      score,
+      scope: record.scope,
+    },
+    {
+      operation: "CastleSaveVariableToLeaderboard",
+      token,
+      requireAuth: true,
+    },
+  );
+}
+
+function leaderboardVariables(request: LeaderboardRequest): GraphqlVariables {
+  return {
+    deckId: request.deckId,
+    variable: request.variable,
+    type: request.type,
+    filter: "dedupUsers",
+    includeFollowList: false,
+    includeParties: false,
+    scope: request.scope,
+  };
+}
+
+function leaderboardFields(): string {
+  return `{
+    yourScore { score }
+    list {
+      place
+      score
+      user {
+        userId
+        username
+      }
+    }
+  }`;
+}
+
+function leaderboardScope(options: LeaderboardOptions): string | null {
+  return options.scope ?? null;
+}
+
+function normalizeLeaderboard(
+  leaderboard: GraphqlLeaderboard,
+  userId: string | null,
+): LeaderboardData {
+  const list = (leaderboard.list ?? []).map(normalizeLeaderboardEntry);
+  const playerRank = playerRankFromList(list, userId);
+  const playerValue = scoreNumber(leaderboard.yourScore?.score);
+  return {
+    list,
+    ...(playerRank === undefined ? {} : { playerRank }),
+    ...(playerValue === undefined ? {} : { playerValue }),
+  };
+}
+
+function normalizeLeaderboardEntry(
+  entry: GraphqlLeaderboardEntry,
+): LeaderboardEntry {
+  const userId = entry.user?.userId ?? undefined;
+  return {
+    place: scoreNumber(entry.place) ?? 0,
+    value: scoreNumber(entry.score) ?? 0,
+    username: entry.user?.username ?? "",
+    ...(userId ? { userId } : {}),
+  };
+}
+
+function playerRankFromList(
+  list: LeaderboardEntry[],
+  userId: string | null,
+): number | undefined {
+  return userId
+    ? list.find((entry) => entry.userId === userId)?.place
+    : undefined;
+}
+
+function scoreNumber(
+  value: string | number | null | undefined,
+): number | undefined {
+  if (typeof value === "number")
+    return Number.isFinite(value) ? value : undefined;
+  if (typeof value !== "string") return undefined;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function leaderboardWriteKey(
+  deckId: string,
+  variable: string,
+  scope: string | null,
+): string {
+  return `${deckId}::${variable}${scope ? `::${scope}` : ""}`;
+}
+
+function assertLeaderboardVariable(variable: string, operation: string): void {
+  if (variable.trim().length > 0) return;
+  throw new CastleError({
+    code: "INVALID_LEADERBOARD_VARIABLE",
+    message: "Leaderboard variable must be a non-empty string.",
+    operation,
+  });
+}
+
+function assertLeaderboardScore(score: number, operation: string): void {
+  if (Number.isFinite(score)) return;
+  throw new CastleError({
+    code: "INVALID_LEADERBOARD_SCORE",
+    message: "Leaderboard score must be a finite number.",
+    operation,
+  });
+}
+
+function assertLeaderboardType(type: LeaderboardSort, operation: string): void {
+  if (type === "high" || type === "low") return;
+  throw new CastleError({
+    code: "INVALID_LEADERBOARD_TYPE",
+    message: "Leaderboard type must be high or low.",
+    operation,
+  });
+}
+
+function reportLeaderboardError(error: unknown): void {
+  console.warn("Castle leaderboard request failed", error);
+}