castle-web-sdk 0.4.3 → 0.4.5

package/src/leaderboard.ts

@@ -1,7 +1,10 @@
-import { getAuth, requireAuthToken } from "./auth";
-import { isEdit, requireDeckId } from "./context";
+import {
+  type RawLeaderboard,
+  type RawLeaderboardEntry,
+} from "./commands";
+import { isEdit } from "./context";
 import { CastleError } from "./errors";
-import { graphqlRequest, type GraphqlVariables } from "./graphql";
+import { hostRequest } from "./transport";
 
 export type LeaderboardSort = "high" | "low";
 export type LeaderboardScope = string;
@@ -23,17 +26,7 @@ export interface LeaderboardData {
   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;
@@ -48,32 +41,10 @@ interface LeaderboardWriteJob {
   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;
 
+// Host stamps deckId, so one deck session = one set of leaderboards; key by
+// variable+scope only and keep the best high/low score per key until flush.
 const leaderboardWrites = new Map<string, PendingLeaderboardWrite>();
 let leaderboardFlushTimer: ReturnType<typeof setTimeout> | null = null;
 let leaderboardFlushPromise: Promise<void> | null = null;
@@ -103,9 +74,11 @@ function writeLeaderboard(
   options: LeaderboardOptions,
 ): void {
   if (isEdit()) return;
-  void bufferLeaderboardWrite(variable, score, options).catch(
-    reportLeaderboardError,
-  );
+  try {
+    bufferLeaderboardWrite(variable, score, options);
+  } catch (error) {
+    reportLeaderboardError(error);
+  }
 }
 
 async function fetchLeaderboardData(
@@ -113,47 +86,81 @@ async function fetchLeaderboardData(
   type: LeaderboardSort,
   options: LeaderboardOptions,
 ): Promise<LeaderboardData> {
-  const request = await leaderboardRequest(
-    "Leaderboard.fetch",
+  assertLeaderboardVariable(variable, "Leaderboard.fetch");
+  assertLeaderboardType(type, "Leaderboard.fetch");
+  const scope = leaderboardScope(options);
+  // If the deck has written a score for this variable+scope this session, send
+  // it so the host writes-and-reads via leaderboardV2 and the player's own
+  // score shows up immediately (mirrors getLeaderboard in
+  // core/src/leaderboards.cpp — presence of a buffered score, not dirtiness,
+  // gates the write-through). Otherwise a plain read of the settled board.
+  const record = leaderboardWrites.get(leaderboardWriteKey(variable, scope));
+  const score = record
+    ? type === "high"
+      ? record.highScore
+      : record.lowScore
+    : null;
+  const { leaderboard, currentUserId } = await hostRequest("leaderboard.fetch", {
     variable,
     type,
-    options,
-  );
-  return normalizeLeaderboard(await fetchLeaderboard(request), request.userId);
+    scope,
+    ...(score === null ? {} : { score }),
+  });
+  if (record && score !== null) {
+    clearLeaderboardDirtyAfterFetch(record, type, score);
+  }
+  return normalizeLeaderboard(leaderboard, currentUserId);
 }
 
-async function bufferLeaderboardWrite(
+// After a write-through fetch, clear the dirty flag for the side we just sent
+// (so the periodic flush won't re-send it via saveVariableToLeaderboard). If
+// the other side's buffered value matches what we sent (the common single-score
+// case where high == low), clear it too. The equality guards skip clearing if a
+// concurrent write bumped the buffered score while the fetch was in flight —
+// that newer score still needs flushing. Mirrors leaderboards.cpp.
+function clearLeaderboardDirtyAfterFetch(
+  record: PendingLeaderboardWrite,
+  type: LeaderboardSort,
+  sentScore: number,
+): void {
+  if (type === "high") {
+    if (record.highScore === sentScore) {
+      record.isHighDirty = false;
+      if (record.lowScore === sentScore) record.isLowDirty = false;
+    }
+  } else {
+    if (record.lowScore === sentScore) {
+      record.isLowDirty = false;
+      if (record.highScore === sentScore) record.isHighDirty = false;
+    }
+  }
+}
+
+function bufferLeaderboardWrite(
   variable: string,
   score: number,
   options: LeaderboardOptions,
-): Promise<void> {
+): 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 key = leaderboardWriteKey(variable, scope);
   const record = leaderboardWrites.get(key);
   if (record) {
     updatePendingLeaderboardWrite(record, score);
   } else {
-    leaderboardWrites.set(
-      key,
-      newPendingLeaderboardWrite(deckId, variable, scope, score),
-    );
+    leaderboardWrites.set(key, newPendingLeaderboardWrite(variable, scope, score));
   }
   ensureLeaderboardUnloadFlush();
   scheduleLeaderboardFlush();
 }
 
 function newPendingLeaderboardWrite(
-  deckId: string,
   variable: string,
   scope: string | null,
   score: number,
 ): PendingLeaderboardWrite {
   return {
-    deckId,
     variable,
     scope,
     highScore: score,
@@ -203,11 +210,8 @@ async function flushLeaderboardWrites(): Promise<void> {
 }
 
 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);
+  for (const job of leaderboardWriteJobs()) {
+    await saveLeaderboardScore(job.record, job.score);
     markLeaderboardWriteClean(job);
   }
 }
@@ -248,131 +252,19 @@ function hasDirtyLeaderboardWrites(): boolean {
   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;
+  await hostRequest("leaderboard.save", {
+    variable: record.variable,
+    score,
+    scope: record.scope,
+  });
 }
 
 function normalizeLeaderboard(
-  leaderboard: GraphqlLeaderboard,
+  leaderboard: RawLeaderboard,
   userId: string | null,
 ): LeaderboardData {
   const list = (leaderboard.list ?? []).map(normalizeLeaderboardEntry);
@@ -386,7 +278,7 @@ function normalizeLeaderboard(
 }
 
 function normalizeLeaderboardEntry(
-  entry: GraphqlLeaderboardEntry,
+  entry: RawLeaderboardEntry,
 ): LeaderboardEntry {
   const userId = entry.user?.userId ?? undefined;
   return {
@@ -416,12 +308,12 @@ function scoreNumber(
   return Number.isFinite(parsed) ? parsed : undefined;
 }
 
-function leaderboardWriteKey(
-  deckId: string,
-  variable: string,
-  scope: string | null,
-): string {
-  return `${deckId}::${variable}${scope ? `::${scope}` : ""}`;
+function leaderboardWriteKey(variable: string, scope: string | null): string {
+  return `${variable}${scope ? `::${scope}` : ""}`;
+}
+
+function leaderboardScope(options: LeaderboardOptions): string | null {
+  return options.scope ?? null;
 }
 
 function assertLeaderboardVariable(variable: string, operation: string): void {

package/src/passes.ts

@@ -0,0 +1,95 @@
+// Pass — a deck-facing capability for selling a creator "pass" to the player.
+//
+// The deck stays capability-AGNOSTIC: it just offers a pass to the player and
+// gets back one normalized outcome regardless of platform. The host decides what
+// UI to show and whether a real transaction can happen:
+//   - mobile app : renders the native bricks purchase sheet over the deck
+//   - web player : shows an "open in the app" upsell, returns `unavailable`
+//   - dev CLI    : no host UI surface, so the SDK shows a minimal in-page
+//                  notice itself (kept deliberately tiny), returns `unavailable`
+// There is no capability check for the deck to make — every platform returns a
+// PassOfferResult, so a single code path handles them all.
+
+import type { PassOfferResult, PassOfferStatus } from "./commands";
+import { CastleError } from "./errors";
+import { getCommandChannel, hostRequest } from "./transport";
+
+export type { PassOfferResult, PassOfferStatus } from "./commands";
+
+export interface CastlePassApi {
+  has(passId: string): Promise<boolean>;
+  offer(passId: string): Promise<PassOfferResult>;
+}
+
+export const Pass: CastlePassApi = {
+  has,
+  offer,
+};
+
+// Pure read — does the current player already own this pass? No UI, every
+// platform answers it the same way (a GraphQL query). Use it to gate content or
+// to decide whether to bother calling `offer`.
+async function has(passId: string): Promise<boolean> {
+  if (typeof passId !== "string" || passId.length === 0) {
+    throw new CastleError({
+      code: "INVALID_ARGUMENT",
+      message: "Pass.has requires a passId.",
+      operation: "Pass.has",
+    });
+  }
+  const { hasPass } = await hostRequest("pass.has", { passId });
+  return hasPass;
+}
+
+async function offer(passId: string): Promise<PassOfferResult> {
+  if (typeof passId !== "string" || passId.length === 0) {
+    throw new CastleError({
+      code: "INVALID_ARGUMENT",
+      message: "Pass.offer requires a passId.",
+      operation: "Pass.offer",
+    });
+  }
+  const result = await hostRequest("pass.offer", { passId });
+  // On the dev server there's no host chrome to explain why nothing happened,
+  // so surface a small built-in notice. The mobile/web hosts render their own
+  // UI, so the SDK stays silent there.
+  if (result.status === "unavailable" && getCommandChannel() === "local") {
+    showDevUnavailableNotice();
+  }
+  return result;
+}
+
+let devNoticeEl: HTMLDivElement | null = null;
+let devNoticeTimer: ReturnType<typeof setTimeout> | null = null;
+
+// Minimal, dependency-free toast. Dev-only affordance — not the place for a
+// designed purchase UI.
+function showDevUnavailableNotice(): void {
+  if (typeof document === "undefined") return;
+  if (!devNoticeEl) {
+    devNoticeEl = document.createElement("div");
+    devNoticeEl.textContent = "Passes can only be purchased in the Castle app.";
+    devNoticeEl.style.cssText = [
+      "position:fixed",
+      "left:50%",
+      "bottom:24px",
+      "transform:translateX(-50%)",
+      "max-width:80vw",
+      "padding:10px 16px",
+      "border-radius:8px",
+      "background:rgba(0,0,0,0.82)",
+      "color:#fff",
+      "font:500 13px/1.4 system-ui,sans-serif",
+      "text-align:center",
+      "z-index:2147483647",
+      "pointer-events:none",
+      "transition:opacity 0.3s ease",
+    ].join(";");
+    document.body.appendChild(devNoticeEl);
+  }
+  devNoticeEl.style.opacity = "1";
+  if (devNoticeTimer) clearTimeout(devNoticeTimer);
+  devNoticeTimer = setTimeout(() => {
+    if (devNoticeEl) devNoticeEl.style.opacity = "0";
+  }, 3200);
+}

package/src/runtime.ts

@@ -1,3 +1,9 @@
+import {
+  CASTLE_SDK_PROTOCOL,
+  type CommandName,
+  type CommandParams,
+  type CommandResponseEnvelope,
+} from "./commands";
 import { getCastleEmbed, isEdit } from "./context";
 
 export const CARD_RATIO = 5 / 7;
@@ -37,6 +43,17 @@ let logBuffer: OutgoingMessage[] = [];
 let nextRequestId = 1;
 const pendingRequests = new Map<string, PendingRequest>();
 
+// Local-dev command channel: the `castle-web serve` dev server is the host, so
+// SDK commands ride the same websocket runtime.ts already uses for
+// logs/screenshots/restart. Correlated by requestId, separate from the
+// screenshot/write_file request map above.
+const COMMAND_TIMEOUT_MS = 15000;
+const SOCKET_WAIT_TIMEOUT_MS = 10000;
+const pendingCommands = new Map<
+  string,
+  (env: CommandResponseEnvelope) => void
+>();
+
 const origLog = console.log;
 const origWarn = console.warn;
 const origError = console.error;
@@ -175,6 +192,66 @@ function sendLocalRequest(msg: OutgoingMessage): Promise<LocalResponse> {
   });
 }
 
+// Send an SDK command to the dev server and resolve with the raw response
+// envelope (ok/data/error). transport.ts interprets it — error reconstruction
+// stays uniform across all three channels there. Waits for the socket to open
+// so a command issued during startup isn't dropped.
+export function sendLocalCommand<C extends CommandName>(
+  command: C,
+  params: CommandParams[C],
+): Promise<CommandResponseEnvelope> {
+  const requestId = `cmd_${nextRequestId++}`;
+  return new Promise<CommandResponseEnvelope>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      pendingCommands.delete(requestId);
+      reject(new Error(`Timed out waiting for command ${command}.`));
+    }, COMMAND_TIMEOUT_MS);
+    pendingCommands.set(requestId, (env) => {
+      clearTimeout(timeout);
+      pendingCommands.delete(requestId);
+      resolve(env);
+    });
+    waitForSocket()
+      .then((socket) => {
+        socket.send(
+          JSON.stringify({
+            type: "castle_command",
+            castleSdk: CASTLE_SDK_PROTOCOL,
+            requestId,
+            command,
+            params,
+          }),
+        );
+      })
+      .catch((error: unknown) => {
+        clearTimeout(timeout);
+        pendingCommands.delete(requestId);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      });
+  });
+}
+
+function waitForSocket(): Promise<WebSocket> {
+  if (ws && ws.readyState === WebSocket.OPEN) return Promise.resolve(ws);
+  return new Promise<WebSocket>((resolve, reject) => {
+    const start = Date.now();
+    const poll = setInterval(() => {
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        clearInterval(poll);
+        resolve(ws);
+      } else if (Date.now() - start > SOCKET_WAIT_TIMEOUT_MS) {
+        clearInterval(poll);
+        reject(new Error("Castle dev server is not connected."));
+      }
+    }, 100);
+  });
+}
+
+function resolveLocalCommand(msg: CommandResponseEnvelope): void {
+  const pending = pendingCommands.get(msg.requestId);
+  if (pending) pending(msg);
+}
+
 function resolveLocalRequest(msg: LocalResponse): boolean {
   if (!msg.requestId) return false;
   const pending = pendingRequests.get(msg.requestId);
@@ -332,12 +409,41 @@ function handleLocalMessage(msg: IncomingMessage): void {
         });
       });
   } else if (msg.type === "restart") {
-    location.reload();
+    scheduleRestart();
   } else if (msg.type === "write_file_response") {
     resolveLocalRequest(msg);
+  } else if (msg.type === "castle_command_response") {
+    resolveLocalCommand(msg as unknown as CommandResponseEnvelope);
   }
 }
 
+// Restart (from `castle-web restart` / task agents) is debounced so a burst
+// of reload requests -- several tasks finishing close together -- produces
+// one reload. Before reloading, registered hooks run (the kit editor flushes
+// its debounced unsaved edits there) so in-flight work isn't lost.
+const RESTART_DEBOUNCE_MS = 1500;
+let restartTimer: ReturnType<typeof setTimeout> | null = null;
+const beforeRestartHooks = new Set<() => void | Promise<void>>();
+
+export function onBeforeRestart(hook: () => void | Promise<void>): () => void {
+  beforeRestartHooks.add(hook);
+  return () => beforeRestartHooks.delete(hook);
+}
+
+function scheduleRestart(): void {
+  if (restartTimer !== null) clearTimeout(restartTimer);
+  restartTimer = setTimeout(() => {
+    void (async () => {
+      try {
+        await Promise.all([...beforeRestartHooks].map(async (hook) => hook()));
+      } catch {
+        // a failed flush shouldn't block the reload
+      }
+      location.reload();
+    })();
+  }, RESTART_DEBOUNCE_MS);
+}
+
 function localWsUrl(path: string): string {
   const url = new URL(path, location.href);
   url.protocol = location.protocol === "https:" ? "wss:" : "ws:";