castle-web-sdk 0.4.3 → 0.4.5

package/dist/castle.d.ts

@@ -2,7 +2,9 @@ export { isEdit } from "./context";
 export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
 export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardSort, } from "./leaderboard";
-export { CARD_RATIO, initCard, setup, writeFile } from "./runtime";
+export { Pass } from "./passes";
+export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
+export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";
 export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";

package/dist/castle.js

@@ -2,7 +2,8 @@
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
-export { CARD_RATIO, initCard, setup, writeFile } from "./runtime";
+export { Pass } from "./passes";
+export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";
 export { User } from "./user";

package/dist/commands.d.ts

@@ -0,0 +1,117 @@
+import type { Json } from "./types";
+export declare const CASTLE_SDK_PROTOCOL = 1;
+export type StorageBlob = Record<string, string>;
+export type SharedScope = "deck" | "user";
+export interface StorageUpdate {
+    key: string;
+    value: string | null;
+}
+export interface RawLeaderboardEntry {
+    place?: string | number | null;
+    score?: string | number | null;
+    user?: {
+        userId?: string | null;
+        username?: string | null;
+    } | null;
+}
+export interface RawLeaderboard {
+    list?: RawLeaderboardEntry[] | null;
+    yourScore?: {
+        score?: string | number | null;
+    } | null;
+}
+export type PassOfferStatus = "purchased" | "alreadyOwned" | "cancelled" | "unavailable";
+export interface PassOfferResult {
+    status: PassOfferStatus;
+}
+export interface CommandParams {
+    "deckStorage.load": Record<string, never>;
+    "deckStorage.update": {
+        updates: StorageUpdate[];
+    };
+    "sharedDeckStorage.load": {
+        scope: SharedScope;
+        userId?: string | null;
+        keys: string[];
+    };
+    "sharedDeckStorage.update": {
+        scope: SharedScope;
+        updates: StorageUpdate[];
+    };
+    "leaderboard.fetch": {
+        variable: string;
+        type: "high" | "low";
+        scope?: string | null;
+        score?: number | null;
+    };
+    "leaderboard.save": {
+        variable: string;
+        score: number;
+        scope?: string | null;
+    };
+    "user.getCurrent": Record<string, never>;
+    "time.getServerTime": Record<string, never>;
+    "pass.has": {
+        passId: string;
+    };
+    "pass.offer": {
+        passId: string;
+    };
+}
+export interface CommandResult {
+    "deckStorage.load": {
+        blob: StorageBlob;
+    };
+    "deckStorage.update": {
+        blob: StorageBlob;
+    };
+    "sharedDeckStorage.load": {
+        blob: StorageBlob;
+    };
+    "sharedDeckStorage.update": {
+        ok: true;
+    };
+    "leaderboard.fetch": {
+        leaderboard: RawLeaderboard;
+        currentUserId: string | null;
+    };
+    "leaderboard.save": {
+        ok: true;
+    };
+    "user.getCurrent": {
+        user: {
+            userId: string;
+            username: string;
+        } | null;
+    };
+    "time.getServerTime": {
+        timestamp: number;
+        timezoneOffset: number;
+        castleEpochData: Json;
+    };
+    "pass.has": {
+        hasPass: boolean;
+    };
+    "pass.offer": PassOfferResult;
+}
+export type CommandName = keyof CommandParams;
+export interface SerializedCommandError {
+    code: string;
+    message: string;
+    command?: string;
+    extensions?: Record<string, unknown>;
+}
+export interface CommandRequestEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    requestId: string;
+    command: CommandName;
+    params: unknown;
+}
+export interface CommandResponseEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    requestId: string;
+    ok: boolean;
+    data?: unknown;
+    error?: SerializedCommandError;
+}
+export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;

package/dist/commands.js

@@ -0,0 +1,16 @@
+// The SDK↔host command contract. This is the single source of truth for the
+// wire protocol shared by the deck-side command-poster (`transport.ts`) and the
+// host-side executor (`host.ts`). It carries ONLY names and types — no GraphQL
+// query strings and no auth — so importing it into a deck bundle reveals
+// nothing privileged.
+// Marker + protocol version. Doubles as a discriminator so host messages can't
+// be confused with embed.js `castlexyz:` strings or RN console messages.
+export const CASTLE_SDK_PROTOCOL = 1;
+export function isResponseEnvelope(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (record.castleSdk === CASTLE_SDK_PROTOCOL &&
+        typeof record.requestId === "string" &&
+        typeof record.ok === "boolean");
+}

package/dist/context.d.ts

@@ -1,21 +1,8 @@
-export interface CastleDeckContext {
-    deckId?: string | null;
-    cardId?: string | null;
-    sessionId?: string | null;
-}
-interface CastleEmbedAuth {
-    token?: string | null;
-    userId?: string | null;
-}
+export type CastleHost = "web" | "mobile" | "dev";
 export interface CastleEmbed {
     edit?: boolean;
     feed?: boolean;
-    auth?: CastleEmbedAuth;
-    deck?: CastleDeckContext;
-    deckId?: string;
-    cardId?: string;
-    sessionId?: string | null;
-    graphqlEndpoint?: string;
+    host?: CastleHost;
 }
 declare global {
     interface Window {
@@ -24,7 +11,3 @@ declare global {
 }
 export declare function getCastleEmbed(): CastleEmbed | undefined;
 export declare function isEdit(): boolean;
-export declare function configureDeckContext(context: CastleDeckContext): void;
-export declare function getDeckContext(): Promise<CastleDeckContext>;
-export declare function requireDeckId(operation?: string): Promise<string>;
-export {};

package/dist/context.js

@@ -1,7 +1,3 @@
-import { CastleError } from "./errors";
-let configuredDeckContext = {};
-let cachedDeckContext = null;
-let cachedDeckContextPromise = null;
 export function getCastleEmbed() {
     return typeof window === "undefined" ? undefined : window.CastleEmbed;
 }
@@ -17,70 +13,3 @@ export function isEdit() {
     }
     return !!getCastleEmbed()?.edit;
 }
-export function configureDeckContext(context) {
-    configuredDeckContext = cleanDeckContext(context);
-    cachedDeckContext = null;
-    cachedDeckContextPromise = null;
-}
-export async function getDeckContext() {
-    if (cachedDeckContext)
-        return cachedDeckContext;
-    cachedDeckContextPromise ??= resolveDeckContext();
-    return cachedDeckContextPromise;
-}
-export async function requireDeckId(operation = "Castle API request") {
-    const context = await getDeckContext();
-    if (!context.deckId) {
-        throw new CastleError({
-            code: "MISSING_DECK_ID",
-            message: "This Castle API needs a deck id.",
-            operation,
-        });
-    }
-    return context.deckId;
-}
-async function resolveDeckContext() {
-    const embedded = embeddedDeckContext();
-    const local = await localDeckContext();
-    const context = mergeDeckContexts(configuredDeckContext, embedded, local);
-    cachedDeckContext = context;
-    return context;
-}
-function embeddedDeckContext() {
-    const embed = getCastleEmbed();
-    return cleanDeckContext({
-        deckId: embed?.deck?.deckId ?? embed?.deckId,
-        cardId: embed?.deck?.cardId ?? embed?.cardId,
-        sessionId: embed?.deck?.sessionId ?? embed?.sessionId,
-    });
-}
-async function localDeckContext() {
-    try {
-        const res = await fetch("/__castle/context");
-        if (!res.ok)
-            return {};
-        return cleanDeckContext((await res.json()));
-    }
-    catch {
-        return {};
-    }
-}
-function cleanDeckContext(context) {
-    return {
-        deckId: stringOrNull(context.deckId),
-        cardId: stringOrNull(context.cardId),
-        sessionId: stringOrNull(context.sessionId),
-    };
-}
-function mergeDeckContexts(...contexts) {
-    return cleanDeckContext({
-        deckId: contexts.find((context) => context.deckId)?.deckId,
-        cardId: contexts.find((context) => context.cardId)?.cardId,
-        sessionId: contexts.find((context) => context.sessionId)?.sessionId,
-    });
-}
-function stringOrNull(value) {
-    if (typeof value !== "string")
-        return null;
-    return value.length > 0 ? value : null;
-}

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,4 +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 {};