castle-web-sdk 0.4.4 → 0.4.6

package/dist/leaderboard.js

@@ -1,8 +1,9 @@
-import { getAuth, requireAuthToken } from "./auth";
-import { isEdit, requireDeckId } from "./context";
+import { isEdit } from "./context";
 import { CastleError } from "./errors";
-import { graphqlRequest } from "./graphql";
+import { hostRequest } from "./transport";
 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();
 let leaderboardFlushTimer = null;
 let leaderboardFlushPromise = null;
@@ -18,32 +19,78 @@ export const Leaderboard = {
 function writeLeaderboard(variable, score, options) {
     if (isEdit())
         return;
-    void bufferLeaderboardWrite(variable, score, options).catch(reportLeaderboardError);
+    try {
+        bufferLeaderboardWrite(variable, score, options);
+    }
+    catch (error) {
+        reportLeaderboardError(error);
+    }
 }
 async function fetchLeaderboardData(variable, type, options) {
-    const request = await leaderboardRequest("Leaderboard.fetch", variable, type, options);
-    return normalizeLeaderboard(await fetchLeaderboard(request), request.userId);
+    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,
+        scope,
+        ...(score === null ? {} : { score }),
+    });
+    if (record && score !== null) {
+        clearLeaderboardDirtyAfterFetch(record, type, score);
+    }
+    return normalizeLeaderboard(leaderboard, currentUserId);
+}
+// 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, type, sentScore) {
+    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;
+        }
+    }
 }
-async function bufferLeaderboardWrite(variable, score, options) {
+function bufferLeaderboardWrite(variable, score, options) {
     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, variable, scope, score) {
+function newPendingLeaderboardWrite(variable, scope, score) {
     return {
-        deckId,
         variable,
         scope,
         highScore: score,
@@ -89,12 +136,8 @@ async function flushLeaderboardWrites() {
     return leaderboardFlushPromise;
 }
 async function flushLeaderboardWritesOnce() {
-    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);
     }
 }
@@ -131,104 +174,13 @@ function hasDirtyLeaderboardWrites() {
     }
     return false;
 }
-async function leaderboardRequest(operation, variable, type, options) {
-    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) {
-    const data = await graphqlRequest(`
-      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, score, token) {
-    await graphqlRequest(`
-      mutation CastleSaveVariableToLeaderboard(
-        $deckId: ID!
-        $variable: String!
-        $score: Float!
-        $scope: String
-      ) {
-        saveVariableToLeaderboard(
-          deckId: $deckId
-          variable: $variable
-          score: $score
-          scope: $scope
-        )
-      }
-    `, {
-        deckId: record.deckId,
+async function saveLeaderboardScore(record, score) {
+    await hostRequest("leaderboard.save", {
         variable: record.variable,
         score,
         scope: record.scope,
-    }, {
-        operation: "CastleSaveVariableToLeaderboard",
-        token,
-        requireAuth: true,
     });
 }
-function leaderboardVariables(request) {
-    return {
-        deckId: request.deckId,
-        variable: request.variable,
-        type: request.type,
-        filter: "dedupUsers",
-        includeFollowList: false,
-        includeParties: false,
-        scope: request.scope,
-    };
-}
-function leaderboardFields() {
-    return `{
-    yourScore { score }
-    list {
-      place
-      score
-      user {
-        userId
-        username
-      }
-    }
-  }`;
-}
-function leaderboardScope(options) {
-    return options.scope ?? null;
-}
 function normalizeLeaderboard(leaderboard, userId) {
     const list = (leaderboard.list ?? []).map(normalizeLeaderboardEntry);
     const playerRank = playerRankFromList(list, userId);
@@ -261,8 +213,11 @@ function scoreNumber(value) {
     const parsed = Number.parseFloat(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
-function leaderboardWriteKey(deckId, variable, scope) {
-    return `${deckId}::${variable}${scope ? `::${scope}` : ""}`;
+function leaderboardWriteKey(variable, scope) {
+    return `${variable}${scope ? `::${scope}` : ""}`;
+}
+function leaderboardScope(options) {
+    return options.scope ?? null;
 }
 function assertLeaderboardVariable(variable, operation) {
     if (variable.trim().length > 0)

package/dist/passes.d.ts

@@ -0,0 +1,7 @@
+import type { PassOfferResult } from "./commands";
+export type { PassOfferResult, PassOfferStatus } from "./commands";
+export interface CastlePassApi {
+    has(passId: string): Promise<boolean>;
+    offer(passId: string): Promise<PassOfferResult>;
+}
+export declare const Pass: CastlePassApi;

package/dist/passes.js

@@ -0,0 +1,84 @@
+// 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 { CastleError } from "./errors";
+import { getCommandChannel, hostRequest } from "./transport";
+export const Pass = {
+    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) {
+    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) {
+    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 = null;
+let devNoticeTimer = null;
+// Minimal, dependency-free toast. Dev-only affordance — not the place for a
+// designed purchase UI.
+function showDevUnavailableNotice() {
+    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/dist/runtime.d.ts

@@ -1,3 +1,4 @@
+import { type CommandName, type CommandParams, type CommandResponseEnvelope } from "./commands";
 export declare const CARD_RATIO: number;
 interface LocalResponse {
     type: string;
@@ -9,5 +10,6 @@ interface LocalResponse {
 export declare function setup(): void;
 export declare function writeFile(path: string, contents: string): Promise<LocalResponse>;
 export declare function initCard(): HTMLDivElement;
+export declare function sendLocalCommand<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResponseEnvelope>;
 export declare function onBeforeRestart(hook: () => void | Promise<void>): () => void;
 export {};

package/dist/runtime.js

@@ -1,9 +1,17 @@
+import { CASTLE_SDK_PROTOCOL, } from "./commands";
 import { getCastleEmbed, isEdit } from "./context";
 export const CARD_RATIO = 5 / 7;
 let ws = null;
 let logBuffer = [];
 let nextRequestId = 1;
 const pendingRequests = new Map();
+// 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();
 const origLog = console.log;
 const origWarn = console.warn;
 const origError = console.error;
@@ -126,6 +134,61 @@ function sendLocalRequest(msg) {
         ws.send(JSON.stringify(request));
     });
 }
+// 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(command, params) {
+    const requestId = `cmd_${nextRequestId++}`;
+    return new Promise((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) => {
+            clearTimeout(timeout);
+            pendingCommands.delete(requestId);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+function waitForSocket() {
+    if (ws && ws.readyState === WebSocket.OPEN)
+        return Promise.resolve(ws);
+    return new Promise((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) {
+    const pending = pendingCommands.get(msg.requestId);
+    if (pending)
+        pending(msg);
+}
 function resolveLocalRequest(msg) {
     if (!msg.requestId)
         return false;
@@ -187,26 +250,34 @@ async function captureWithHtml2Canvas(target) {
         return null;
     }
 }
+function cropCanvasToCard(card, canvas) {
+    const cardRect = card.getBoundingClientRect();
+    const c = document.createElement("canvas");
+    c.width = cardRect.width * devicePixelRatio;
+    c.height = cardRect.height * devicePixelRatio;
+    const ctx = c.getContext("2d");
+    const canvasRect = canvas.getBoundingClientRect();
+    const dx = (canvasRect.left - cardRect.left) * devicePixelRatio;
+    const dy = (canvasRect.top - cardRect.top) * devicePixelRatio;
+    ctx.drawImage(canvas, dx, dy, canvasRect.width * devicePixelRatio, canvasRect.height * devicePixelRatio);
+    return c.toDataURL("image/png");
+}
 async function captureScreenshot() {
-    const card = document.getElementById("castle-card");
-    const canvas = document.querySelector("canvas");
+    const card = document.querySelector("#castle-card, [data-castle-card]");
+    if (card) {
+        const cardCanvas = card.querySelector("canvas");
+        if (cardCanvas)
+            return cropCanvasToCard(card, cardCanvas);
+        const cropped = await captureWithHtml2Canvas(card);
+        if (cropped)
+            return cropped;
+    }
     if (document.body?.dataset.castleScreenshotTarget === "viewport") {
         const viewportCapture = await captureWithHtml2Canvas(document.body);
         if (viewportCapture)
             return viewportCapture;
     }
-    if (card && canvas) {
-        const cardRect = card.getBoundingClientRect();
-        const c = document.createElement("canvas");
-        c.width = cardRect.width * devicePixelRatio;
-        c.height = cardRect.height * devicePixelRatio;
-        const ctx = c.getContext("2d");
-        const canvasRect = canvas.getBoundingClientRect();
-        const dx = (canvasRect.left - cardRect.left) * devicePixelRatio;
-        const dy = (canvasRect.top - cardRect.top) * devicePixelRatio;
-        ctx.drawImage(canvas, dx, dy, canvasRect.width * devicePixelRatio, canvasRect.height * devicePixelRatio);
-        return c.toDataURL("image/png");
-    }
+    const canvas = document.querySelector("canvas");
     if (canvas)
         return canvas.toDataURL("image/png");
     return captureWithHtml2Canvas(card || document.body);
@@ -280,6 +351,9 @@ function handleLocalMessage(msg) {
     else if (msg.type === "write_file_response") {
         resolveLocalRequest(msg);
     }
+    else if (msg.type === "castle_command_response") {
+        resolveLocalCommand(msg);
+    }
 }
 // Restart (from `castle-web restart` / task agents) is debounced so a burst
 // of reload requests -- several tasks finishing close together -- produces
@@ -298,7 +372,7 @@ function scheduleRestart() {
     restartTimer = setTimeout(() => {
         void (async () => {
             try {
-                await Promise.all([...beforeRestartHooks].map((hook) => hook()));
+                await Promise.all([...beforeRestartHooks].map(async (hook) => hook()));
             }
             catch {
                 // a failed flush shouldn't block the reload

package/dist/storage.d.ts

@@ -1,5 +1,5 @@
+import { type SharedScope } from "./commands";
 import type { Json } from "./types";
-type SharedScope = "deck" | "user";
 export interface StorageApi {
     get<T extends Json = Json>(key: string): Promise<T | null>;
     set(key: string, value: Json): void;
@@ -14,4 +14,3 @@ export interface SharedStorageApi {
 }
 export declare const Storage: StorageApi;
 export declare const SharedStorage: SharedStorageApi;
-export {};